Authentication

All API requests require authentication using an API key.

API Key Format

SMAvatar API keys follow this format:

sma_AqNYHpfSLGz51YEzJwqavCw6rTlxnlka

• Prefix: sma_ (identifies SMAvatar keys)
• Body: 32 random characters (base64url encoded)

Using Your API Key

Include your API key in the Authorization header:

curl 'https://api.smavatar.com/api/v1/...' \
  -H 'Authorization: Bearer sma_YOUR_API_KEY_HERE'

Projects & API Keys

SMAvatar uses a hierarchical structure:

Organization (your account)
└── Project (e.g., "My App")
    └── API Keys (multiple allowed)
        └── Jobs (avatars, maps)

Why Projects?

• Organize different applications separately
• Track usage per project
• Manage access with multiple API keys per project
• Revoke keys without affecting other projects

Creating API Keys

1. Go to your project in the dashboard
2. Navigate to the API Keys tab
3. Click "Create API Key"
4. Give it a descriptive name (e.g., "Production", "Development")
5. Copy the key immediately - you won't see it again!

Security Best Practices

DO

• ✅ Store API keys in environment variables
• ✅ Use different keys for dev/staging/production
• ✅ Rotate keys periodically
• ✅ Revoke keys immediately if compromised

DON'T

• ❌ Commit API keys to version control
• ❌ Expose keys in client-side code
• ❌ Share keys in chat/email
• ❌ Use the same key everywhere

Environment Variables

# .env (never commit this file!)
SMAVATAR_API_KEY=sma_your_key_here
SMAVATAR_PROJECT_ID=your-project-uuid

// Node.js
const apiKey = process.env.SMAVATAR_API_KEY

# Python
import os
api_key = os.environ.get('SMAVATAR_API_KEY')

Rate Limits

API keys have the following rate limits:

Exceeding rate limits returns 429 Too Many Requests.

Revoking Keys

If a key is compromised:

1. Go to your project → API Keys
2. Find the compromised key
3. Click "Revoke"
4. Create a new key
5. Update your applications

Revoked keys stop working immediately.

Error Responses

Invalid API Key

{
  "statusCode": 401,
  "message": "Invalid API key"
}

Missing Authorization Header

{
  "statusCode": 401,
  "message": "Authorization header required"
}

Wrong Project

{
  "statusCode": 403,
  "message": "API key does not have access to this project"
}

Next Steps