API Authentication

Bearer Token Authentication

Bearer token authentication is the simplest method for API access:

Request Format:

GET /api/v1/recordings HTTP/1.1
Host: api.example.com
Authorization: Bearer your_access_token_here
Content-Type: application/json

Example with cURL:

curl -X GET "https://api.example.com/api/v1/recordings" \
  -H "Authorization: Bearer your_access_token_here" \
  -H "Content-Type: application/json"

Example with JavaScript:

const response = await fetch('https://api.example.com/api/v1/recordings', {
  headers: {
    'Authorization': 'Bearer your_access_token_here',
    'Content-Type': 'application/json'
  }
});

Bearer tokens are obtained through:

• User login (for user-initiated requests)
• OAuth 2.0 flow (for third-party applications)
• API client authentication

OAuth 2.0

OAuth 2.0 provides secure, standardized authentication for third-party applications:

OAuth Flow:

1. Authorization Request: Redirect user to authorization endpoint
2. User Consent: User grants permissions to your application
3. Authorization Code: Receive authorization code
4. Token Exchange: Exchange code for access token
5. API Access: Use access token for API requests

Authorization URL:

https://api.example.com/oauth/authorize?
  client_id=your_client_id&
  redirect_uri=your_redirect_uri&
  response_type=code&
  scope=read write

Token Exchange:

POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=authorization_code&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=your_redirect_uri

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200abc123..."
}

API Client Authentication

Authenticate using API client credentials:

Client Credentials Flow:

POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=your_client_id&
client_secret=your_client_secret&
scope=read write

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use client credentials flow for server-to-server communication without user interaction.

Token Management

Manage access tokens effectively:

• Token Storage: Store tokens securely (encrypted storage, environment variables)
• Token Refresh: Use refresh tokens to obtain new access tokens
• Token Expiration: Handle token expiration gracefully
• Token Revocation: Revoke tokens when no longer needed
• Token Rotation: Rotate tokens regularly for security

Refresh Token Example:

POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=your_refresh_token&
client_id=your_client_id&
client_secret=your_client_secret

Token Expiration

Access tokens have expiration times:

• Default Expiration: 1 hour (3600 seconds)
• Refresh Tokens: Longer-lived (30 days default)
• Expiration Headers: API responses include token expiration info
• Automatic Refresh: Implement automatic token refresh in your application

Handle token expiration by:

1. Catching 401 Unauthorized responses
2. Using refresh token to obtain new access token
3. Retrying the original request with new token