Authentication

Avatarium uses API keys and JWT tokens for authentication. This guide explains how to authenticate your requests.

Authentication Methods

API Keys

API keys are the primary authentication method for SDK and direct API access.

Key Format

av_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
av_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• av_live_ prefix: Production keys
• av_test_ prefix: Test/development keys (sandbox mode)

Creating an API Key

1. Sign in to the Dashboard (opens in a new tab)
2. Navigate to Settings > API Keys
3. Click Create API Key
4. Give it a descriptive name (e.g., "Production Website")
5. Copy the key immediately - it won't be shown again

Using API Keys

import { AvatariumEmbed } from '@avatarium/react';
 
// Note: AvatariumEmbed uses iframe embedding (no API key required in component)
// Use your Short ID from the dashboard, not an API key
<AvatariumEmbed
  shortId="YOUR_SHORT_ID"
  mode="voice"
/>

API Key Permissions

API keys have full access to:

• Create and manage conversations
• Send messages and receive responses
• Access avatar information
• TTS synthesis endpoints

JWT Authentication (Dashboard)

Dashboard users authenticate via Firebase JWT tokens. This is used internally by the dashboard application.

How It Works

1. User signs in via Google OAuth
2. Firebase issues a JWT token
3. Token is sent with each API request
4. API verifies token signature against Firebase JWKS

Token Validation

The API validates:

• Signature: Verified against Firebase's public keys (JWKS)
• Issuer: Must be https://securetoken.google.com/<project-id>
• Audience: Must match the Firebase project ID
• Expiration: Token must not be expired

Example JWT Claims

{
  "iss": "https://securetoken.google.com/avatarium-prod",
  "aud": "avatarium-prod",
  "sub": "abc123",
  "user_id": "abc123",
  "email": "user@example.com",
  "email_verified": true,
  "exp": 1705312800,
  "iat": 1705309200
}

Security Best Practices

Do

• Store API keys in environment variables
• Use different keys for development and production
• Rotate keys periodically
• Use server-side proxies for sensitive operations
• Monitor key usage in the dashboard

Don't

• Commit API keys to git repositories
• Expose keys in client-side JavaScript (unless using NEXT_PUBLIC_ pattern)
• Share keys across different applications
• Use production keys in development

Environment Variable Example

# Never commit this file to git
NEXT_PUBLIC_AVATARIUM_KEY=av_live_xxxxx
AVATARIUM_SECRET_KEY=av_live_yyyyy  # Server-side only

// Client-side (visible to users)
<Avatar apiKey={process.env.NEXT_PUBLIC_AVATARIUM_KEY} />

// Server-side (hidden from users)
const response = await fetch('https://api.avatarium.ai/v1/...', {
  headers: {
    'Authorization': `Bearer ${process.env.AVATARIUM_SECRET_KEY}`
  }
});

Rate Limiting by Auth Type

Auth-Specific Rate Limits

Certain sensitive operations have additional limits:

Error Responses

Invalid API Key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked"
  }
}

Missing Authentication

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Provide an API key or JWT token."
  }
}

Expired Token

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Your authentication token has expired. Please sign in again."
  }
}

Troubleshooting

"Invalid API key" Error

1. Verify the key hasn't been revoked in the dashboard
2. Check for extra whitespace in the key
3. Ensure you're using the correct environment (live vs test)
4. Regenerate the key if issues persist

"401 Unauthorized" on First Request

1. Confirm the Authorization header is set correctly
2. Check the Bearer prefix is included
3. Verify the key format (av_live_ or av_test_)

JWT Token Issues

1. Ensure the user is signed in
2. Check token expiration (tokens last 1 hour)
3. Refresh the token if expired
4. Verify Firebase configuration

Next Steps

• API Reference - Full endpoint documentation
• Error Codes - Complete error code reference
• BYOK Guide - Use your own AI provider keys