Access Tokens

Access tokens are short-lived credentials that grant temporary access to specific Audian API resources. They're ideal for time-limited operations and client-side use cases.

Overview

Access tokens are different from API keys and OAuth tokens:

Aspect	Access Token	API Key	OAuth Token
Lifespan	15 minutes - 24 hours	No expiration	1 hour
Scope	Specific resources	Multiple scopes	User-delegated scopes
Use Case	Temporary access	Permanent server access	User-facing apps
Best For	Client-side operations	Backend services	Third-party integrations

Creating Access Tokens

Via Dashboard

1. Log in to my.audian.com
2. Navigate to API > Access Tokens
3. Click Generate Token
4. Select:
   • Resource Type: (Audio, Job, etc.)
   • Resource ID: Specific resource to access
   • Permissions: read, write, delete
   • Expiration: 15 min - 24 hours
5. Click Generate
6. Copy and store the token

Via API

Generate a token programmatically:

curl -X POST https://api.audian.com:8443/v2/access-tokens \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "audio",
    "resource_id": "audio_abc123",
    "permissions": ["read"],
    "expires_in": 3600
  }'

Response:

{
  "id": "token_xyz789",
  "token": "temp_abc123xyz_exp_1707145800",
  "resource_type": "audio",
  "resource_id": "audio_abc123",
  "permissions": ["read"],
  "created_at": "2025-02-04T10:30:00Z",
  "expires_at": "2025-02-04T11:30:00Z"
}

Token Types

Audio File Access

Grant access to read a specific audio file:

curl -X POST https://api.audian.com:8443/v2/access-tokens \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "audio",
    "resource_id": "audio_abc123",
    "permissions": ["read"],
    "expires_in": 3600
  }'

Use the token:

curl -X GET https://api.audian.com:8443/v2/audio/audio_abc123 \
  -H "X-Auth-Token: temp_abc123xyz_exp_1707145800"

Processing Job Access

Grant access to a specific processing job:

curl -X POST https://api.audian.com:8443/v2/access-tokens \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "job",
    "resource_id": "job_def456",
    "permissions": ["read"],
    "expires_in": 3600
  }'

Download Access

Create a download token for a client to retrieve an audio file:

curl -X POST https://api.audian.com:8443/v2/access-tokens \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "audio",
    "resource_id": "audio_abc123",
    "permissions": ["download"],
    "expires_in": 86400
  }'

Share the token with a client:

# Client can now download
curl -X GET https://api.audian.com:8443/v2/audio/audio_abc123/download \
  -H "X-Auth-Token: temp_abc123xyz_exp_1707232200" \
  -o audio.mp3

Use Cases

1. Sharing Audio with Clients

Generate a time-limited download token:

import requests
from datetime import datetime, timedelta

api_key = 'your_api_key'
audio_id = 'audio_abc123'

# Generate token that expires in 24 hours
response = requests.post(
    'https://api.audian.com:8443/v2/access-tokens',
    headers={
        'X-Auth-Token': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'resource_type': 'audio',
        'resource_id': audio_id,
        'permissions': ['download'],
        'expires_in': 86400  # 24 hours
    }
)

token = response.json()['token']
download_url = f'https://api.audian.com:8443/v2/audio/{audio_id}/download?token={token}'
print(f"Share this link: {download_url}")

2. Client-Side Processing Status

Grant client access to check job status:

// Backend creates token for client
async function generateJobAccessToken(jobId) {
  const response = await fetch('https://api.audian.com:8443/v2/access-tokens', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      resource_type: 'job',
      resource_id: jobId,
      permissions: ['read'],
      expires_in: 3600
    })
  });
  
  const { token } = await response.json();
  return token;
}

// Frontend checks status with token
async function checkJobStatus(jobId, accessToken) {
  const response = await fetch(
    `https://api.audian.com:8443/v2/processing/jobs/${jobId}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );
  
  return response.json();
}

3. Temporary API Access

Create short-lived tokens for specific operations:

# Create 15-minute token for reading specific audio
curl -X POST https://api.audian.com:8443/v2/access-tokens \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "audio",
    "resource_id": "audio_abc123",
    "permissions": ["read"],
    "expires_in": 900
  }'

# Token expires after 15 minutes of creation

Permissions

Access token permissions are granular:

Read Permissions

• read: View resource metadata and details
• read:results: Access processing results

Write Permissions

• write: Modify resource
• write:metadata: Update resource metadata

Delete Permissions

• delete: Delete resource

Download Permissions

• download: Download audio file
• download:results: Download processing results

Expiration

Setting Expiration

Tokens expire after a specified duration:

# 15 minutes
-d '{"expires_in": 900}'

# 1 hour
-d '{"expires_in": 3600}'

# 24 hours
-d '{"expires_in": 86400}'

Maximum Expiration

Tokens can live up to 24 hours (86,400 seconds). Longer durations are capped at this maximum.

After Expiration

Expired tokens return a 401 error:

{
  "error": {
    "code": "token_expired",
    "message": "The access token has expired",
    "expired_at": "2025-02-04T11:30:00Z"
  }
}

Revoking Tokens

Revoke a token before expiration:

curl -X DELETE https://api.audian.com:8443/v2/access-tokens/token_xyz789 \
  -H "X-Auth-Token: YOUR_API_KEY"

Token Security

Storage

For client-side use:

// Store in sessionStorage (not persistent)
sessionStorage.setItem('audian_token', token);

// Retrieve when needed
const token = sessionStorage.getItem('audian_token');

For server-side use:

# Store securely in memory
self.access_token = token
# Or in secure cache with expiration
cache.set(f'token:{token_id}', token, expire=3600)

Best Practices

• Always use HTTPS when transmitting tokens
• Don't include tokens in URLs (use Authorization header)
• Set expiration to minimum necessary duration
• Revoke tokens after use if no longer needed
• Don't log token values
• Use different tokens for different purposes

Never

• Commit tokens to version control
• Log token values
• Share tokens across environments
• Use tokens in browser localStorage (use sessionStorage)
• Hard-code tokens in applications

Troubleshooting

"Token Expired"

Token has reached its expiration time:

1. Generate a new token
2. Check expiration time before using
3. Increase expires_in if needed

"Invalid Token"

Token format or signature is invalid:

1. Verify token was copied correctly
2. Check token hasn't been modified
3. Generate a new token

"Token Not Found"

Token doesn't exist or was already revoked:

1. Generate a new token
2. Check token ID is correct

Examples

Complete Workflow

import requests
import time

API_KEY = 'your_api_key'
AUDIO_ID = 'audio_abc123'

# 1. Create a short-lived token
print("Generating access token...")
response = requests.post(
    'https://api.audian.com:8443/v2/access-tokens',
    headers={
        'X-Auth-Token': API_KEY,
        'Content-Type': 'application/json'
    },
    json={
        'resource_type': 'audio',
        'resource_id': AUDIO_ID,
        'permissions': ['read', 'download'],
        'expires_in': 3600
    }
)

token_data = response.json()
access_token = token_data['token']
print(f"Token expires at: {token_data['expires_at']}")

# 2. Use the token
print("\nUsing token to read audio...")
response = requests.get(
    f'https://api.audian.com:8443/v2/audio/{AUDIO_ID}',
    headers={'X-Auth-Token': access_token}
)

audio_data = response.json()
print(f"Audio: {audio_data['filename']}")

# 3. Token will auto-expire
# No need to manually revoke

Next Steps

• API Keys: See API Keys
• OAuth: Learn OAuth 2.0
• Security: Review Security Best Practices