Authentication

Method 1: JWT Token

JWT (JSON Web Token) authentication is ideal for user-facing applications where a user logs in with their credentials. The token is short-lived and must be refreshed periodically.

1. Obtain a Token

Send a POST request to the login endpoint with your credentials:

curl -X POST https://api.voicecraft.ai/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your_password"
  }'

Response:

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

2. Use the Token

Include the token in the Authorization header of every subsequent request:

curl https://api.voicecraft.ai/api/v1/agents \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Python Example

import requests

# Login to get JWT token
response = requests.post(
    "https://api.voicecraft.ai/api/v1/auth/login",
    json={
        "email": "you@example.com",
        "password": "your_password",
    },
)
token = response.json()["access_token"]

# Use the token for authenticated requests
agents = requests.get(
    "https://api.voicecraft.ai/api/v1/agents",
    headers={"Authorization": f"Bearer {token}"},
)
print(agents.json())

Method 2: API Key

API keys are recommended for server-to-server integrations, background jobs, and automated workflows. They do not expire but can be revoked at any time from the dashboard.

1. Create an API Key

Go to Settings → API Keys in the VoiceCraft AI dashboard. Click "Create New Key", assign a descriptive name, and copy the key. It will be prefixed with vc_.

2. Use the API Key

You can pass the API key using either the X-API-Key header or the Authorization header with a Bearer prefix:

Option A: X-API-Key Header

curl https://api.voicecraft.ai/api/v1/agents \
  -H "X-API-Key: vc_your_api_key_here"

Option B: Bearer Token Format

curl https://api.voicecraft.ai/api/v1/agents \
  -H "Authorization: Bearer vc_your_api_key_here"

Python Example

import requests

# Using X-API-Key header
agents = requests.get(
    "https://api.voicecraft.ai/api/v1/agents",
    headers={"X-API-Key": "vc_your_api_key_here"},
)
print(agents.json())

# Or use the SDK (recommended)
from voicecraft import VoiceCraftClient

client = VoiceCraftClient(api_key="vc_your_api_key_here")
agents = client.agents.list()
print(agents)

Rate Limiting

All API endpoints are rate-limited to ensure fair usage and platform stability. Limits vary by plan:

When you exceed a rate limit, the API responds with a 429 Too Many Requests status code. The Retry-After header indicates when you can retry.