Authentication
How Specala AI API keys work — create an sk_live_ key, send it as a Bearer token in the Authorization header, plus scopes, rate limits and security.
The Specala AI Developer API uses API keys (personal access tokens). One key authenticates both the REST API and the local MCP server.
The remote MCP connector doesn't need a key
If you're connecting Claude, ChatGPT or another assistant via the hosted connector
(https://mcp.specala.ai/mcp), authentication is OAuth: you sign in with your Specala AI
account and click Allow — no API key involved. The assistant gets read-only access to one
workspace, and tokens rotate automatically. See the
MCP Quickstart. API keys below are for the REST API, the local npm
server, and scripts.
Creating a key
In the web app, open Settings → API & MCP and click Create key. You'll see the full key once — copy it immediately and store it somewhere safe.
Create API key- Keys start with the
sk_live_prefix. - Only the key's suffix (last few characters) is stored for display — the key itself is hashed (SHA-256) and never recoverable. If you lose it, create a new one.
- You can set an optional expiry date. After it passes, the key stops working.
Plan requirement
API & MCP access is available on Pro and Expert plans. Calls with a key on a plan
without API access return 403 api_access_denied.
Using a key
Send the key as a Bearer token in the Authorization header:
curl https://app.specala.ai/api/v1/developer/transcriptions \
-H "Authorization: Bearer sk_live_your_key_here"Never put keys in the URL
Passing a key as a query parameter is rejected with 401. URLs leak into logs, browser
history and analytics — always use the Authorization header.
Scope: workspace-level
A key is bound to one workspace and acts on behalf of the member who created it:
- It can read and export transcriptions in that workspace only.
- Every member of a workspace can create their own keys.
- A workspace OWNER can see (and revoke) all keys in the workspace; other members see only their own.
- If the creating member loses access to the workspace, the key is automatically deactivated.
To work with multiple workspaces, create one key per workspace.
Key permissions
Keys are read-only by default: they can list, fetch and export transcriptions — nothing else. Write operations are separate, deliberate permissions you enable when creating a key:
| Permission | Unlocks | Without it |
|---|---|---|
| Allow file uploads | Upload a file | 403 upload_scope_required |
| Allow deleting transcriptions | Delete transcription — irreversible | 403 delete_scope_required |
- Permissions are chosen at creation time and can't be changed later. To add one to an integration, create a new key and retire the old one.
- Keys created before permissions existed are read-only.
- Each permission is independent — an upload key can't delete, and vice versa.
Keep automation that only reads on read-only keys, and grant deletion only to the one integration that truly needs it — if a read-only key ever leaks, nobody can spend your minutes or destroy your data with it.
Rate limits
Limits are applied per key:
| Surface | Limit |
|---|---|
| Data endpoints (list / get / export / bulk) | 500 requests / minute |
| Export volume | 10 GB / day |
| File uploads | 60 requests / minute, 10 concurrent per key (16 per workspace) |
| Deletions | 30 requests / minute |
| Key management (create / list / update / revoke) | 180 requests / minute |
Uploads also have generous daily anti-abuse caps (hundreds of files / ~100 GB per key per day) — normal integrations never hit them; contact support if you do.
Exceeding a limit returns 429 Too Many Requests. Back off and retry after a
short pause; don't hammer with automatic immediate retries.
Revoking a key
In Settings → API & MCP, delete a key to revoke it immediately. Any further request with
that key returns 401. Revocation can't be undone — issue a new key to restore access.
Security best practices
- Store keys as secrets — environment variables or a secrets manager, never in source control.
- One key per integration so you can revoke a single one without breaking the others.
- Set an expiry for short-lived or third-party use.
- Rotate periodically: create the new key, switch your integration over, then delete the old one.
- Scope down: use a dedicated workspace for an integration when it only needs a subset of data.