Authentication

Create API tokens, understand drive scoping, and configure authentication for API requests.

The Descript API uses bearer token authentication. Every API request must include your token in the Authorization header.

curl https://descriptapi.com/v1/status \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Using an AI assistant? The MCP connector (for Claude, Cursor, and other AI tools) handles authentication via OAuth. You don’t need an API token — just connect through your AI assistant’s settings. See the MCP guide.

Create an API token

1. Open API token settings

   In Descript, go to Settings > API tokens.

2. Create a new token

   Click Create token. Give it a name and select the Drive it should be associated with.

3. Copy and store your token

   Copy the token immediately — you won’t be able to view it again. If you lose it, generate a new one.

Treat your API token like a password. Anyone with your token can make API requests on your behalf. Never share it publicly or commit it to source control.

Drive scoping

Each API token is scoped to a single Descript Drive. This means:

• The token can only access projects in its associated Drive
• Attempting to edit a project in a different Drive returns a 403 error, even if your account has access to that Drive
• If you work across multiple Drives, create a separate token for each

Using the token

Include the token as a Bearer token in the Authorization header of every request:

cURL

curl https://descriptapi.com/v1/jobs \
  -H "Authorization: Bearer dsc_your_api_token_here"

Error responses

Status Code	Meaning	What to do
401	Missing or invalid token	Check that you’re including the Authorization header with a valid token
402	Insufficient credits	Your account has run out of media minutes or AI credits
403	Wrong Drive	The token doesn’t have access to the requested project’s Drive

Token management

• Tokens don’t expire automatically, but you can revoke them at any time in Settings
• Create descriptive names (e.g., “Production automation”, “CI pipeline”) so you know what each token is for
• Use separate tokens for different environments or use cases so you can revoke one without affecting others

Rate limits

Rate limits exist for infrastructure stability, not to cap the value you get from the API.

Endpoint	Limit
POST /jobs/import/project_media	10 requests per minute
POST /jobs/agent	10 requests per minute
GET /jobs/{job_id}	20 requests per second per user

When you exceed a limit, the API returns 429 Too Many Requests with these headers:

Header	Description
Retry-After	Seconds to wait before retrying
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Consumed	Requests consumed in the current window

Always respect the Retry-After header — don’t retry immediately on a 429.