​
API Authentication

Secure access to the AuthentiVoice API using JWT tokens and API keys.

​
Overview

AuthentiVoice uses a dual authentication system:
  • JWT Tokens: For user-specific operations and frontend authentication
  • API Keys: For server-to-server communication and integrations
All API requests must include authentication credentials in the request headers.

​
Authentication Methods

​
JWT Token Authentication

1

Obtain Token

Authenticate via Supabase Auth to receive a JWT token
2

Include in Headers

Add the token to the Authorization header
3

Handle Expiration

Refresh tokens before they expire (typically 1 hour)
Request Example: 
curl -X GET https://api.authentivoice.com/v1/analyses \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

​
API Key Authentication

For server-to-server communication: 
curl -X GET https://api.authentivoice.com/v1/analyses \
  -H "X-API-Key: your-api-key-here"
API keys have full access to your account. Keep them secure and never expose them in client-side code.

​
Obtaining Credentials

​
JWT Tokens via Supabase

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  'https://your-project.supabase.co',
  'your-anon-key'
)

// Sign in
const { data, error } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'secure-password'
})

// Access token
const token = data.session.access_token

// Use in API calls
const response = await fetch('https://api.authentivoice.com/v1/analyses', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})

​
API Key Generation

1

Navigate to API Settings

Go to Settings → API → Keys in the dashboard
2

Create New Key

Click “Generate New Key” and configure:
  • Key name for identification
  • Expiration date (optional)
  • Permission scopes
3

Save Key Securely

Copy the key immediately - it won’t be shown again

​
Permission Scopes

​
Available Scopes

​
Scope Combinations

Common permission sets:

Read-Only Access

read:analyses, read:reviews

Reviewer Access

read:analyses, read:reviews, write:reviews

Full Access

All scopes enabled

Integration Access

write:analyses, read:analyses

​
Security Headers

​
Required Headers

All authenticated requests must include:

​
Optional Security Headers

​
Token Management

​
Token Refresh

JWT tokens expire after 1 hour. Implement automatic refresh: 
class ApiClient {
  constructor(supabase) {
    this.supabase = supabase
  }

  async makeRequest(url, options = {}) {
    // Get current session
    const { data: { session } } = await this.supabase.auth.getSession()
    
    if (!session) {
      throw new Error('Not authenticated')
    }

    // Check if token expires soon (within 5 minutes)
    const expiresAt = session.expires_at * 1000
    const expiresIn = expiresAt - Date.now()
    
    if (expiresIn < 5 * 60 * 1000) {
      // Refresh token
      const { data, error } = await this.supabase.auth.refreshSession()
      if (error) throw error
      session = data.session
    }

    // Make request with fresh token
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${session.access_token}`
      }
    })
  }
}

​
API Key Rotation

Best practices for API key management:
1

Regular Rotation

Rotate keys every 90 days
2

Multiple Keys

Maintain 2 active keys during rotation
3

Gradual Migration

Update integrations before revoking old keys
4

Audit Usage

Monitor key usage in audit logs

​
Error Responses

​
Authentication Errors

Error Response Format: 
{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Authentication token has expired",
    "details": {
      "expired_at": "2024-01-15T10:30:00Z"
    }
  }
}

​
Rate Limiting

​
Default Limits

​
Rate Limit Headers

Monitor your usage with response headers: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642255200
X-RateLimit-Reset-After: 3600

​
Security Best Practices

  • Never store tokens in localStorage (use secure cookies)
  • Implement token refresh before expiration
  • Clear tokens on logout
  • Use HTTPS for all API calls
  • Store keys in environment variables
  • Never commit keys to version control
  • Use different keys for different environments
  • Implement key rotation schedule
  • Validate SSL certificates
  • Implement request signing for sensitive operations
  • Use request IDs for tracking
  • Log authentication failures
  • Whitelist IP addresses when possible
  • Use webhook signatures
  • Implement retry with backoff
  • Monitor for unusual patterns

​
Testing Authentication

​
cURL Examples

# Test with JWT token
curl -X GET https://api.authentivoice.com/v1/analyses \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -v

​
Next Steps

1

Generate Credentials

Create your first API key or obtain JWT token
2

Test Authentication

Verify your credentials work with a simple GET request
3

Implement Token Refresh

Set up automatic token refresh in your application
4

Monitor Usage

Track your API usage and rate limits