API keys
Create, use and revoke the keys that authenticate the Subtitle AI API.
An API key lets a machine call the Job API on behalf of your organization. Owners and admins create and revoke keys in the app.
What a key can do
- It belongs to one organization. It can read and create jobs anywhere in that organization, not only in projects its creator can see. It can never reach another organization's data: a job id from elsewhere answers
404, the same as an id that does not exist. - It has full access. Keys cannot be limited to reading or to submitting yet.
- It works on the API only. A key does not sign anyone in to the web app.
- It acts for your organization's credits. Jobs created with a key use the same credits as jobs uploaded in the app.
A key looks like this:
sk_live_<43 characters>Create a key
Sign in as an organization owner or admin. Other roles do not see the page.
Open API Keys in the sidebar, in the admin section next to Team Members and Subscription.
Click Create API Key and give it a label, such as Newsroom watch folder. The label is only for you.
Copy the key from the dialog and store it in a secret manager. It is shown once. Subtitle AI keeps only a hash of it and cannot show it again. If you lose it, revoke it and create another.
Each key then appears in the list with its label, its first 16 characters (for example sk_live_a1b2c3d4…), when it was created and when it was last used.
Use a key
Send it as a bearer token on every request:
curl https://app.subtitle.ai/api/v1/jobs/JOB_ID \
-H "Authorization: Bearer $SUBTITLE_AI_KEY"Keep the key in an environment variable or a secret manager. Never put it in source control, a web page or a mobile app. Anyone who has the key can create jobs that spend your credits.
Revoke a key
In the list, click Revoke and confirm. The key stops working on its next request. Jobs it already created stay in your organization. Revoking cannot be undone, and the key stays in the list marked Revoked.
If a key may have leaked, revoke it first and replace it afterwards.
Rate limit
Each key can make 120 requests per minute. Over that, the API answers 429 with code: "rate_limited" and a Retry-After header. Wait that many seconds, then retry. Two keys do not share a limit, so give each integration its own key.
Polling a job every 10 to 30 seconds is well within the limit.
When authentication fails
All three answer 401 with a JSON body:
code | Meaning |
|---|---|
missing_api_key | There is no Authorization: Bearer … header. |
malformed_api_key | The value is not shaped like a Subtitle AI key. Check for a copy and paste error. |
invalid_api_key | The key does not exist, or it was revoked. |
Good practice
- Make one key for each integration and label it clearly. You can then revoke one without breaking the others.
- Check Last used now and then. A key that should be idle but was used recently deserves a look.
- Rotate keys when people who had access leave.