# API keys (/docs/api/authentication)



An API key lets a machine call the [Job API](./index.mdx) on behalf of your organization. Owners and admins create and revoke keys in the app.

What a key can do [#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:

```text
sk_live_<43 characters>
```

Create a key [#create-a-key]

<Steps>
  <Step>
    Sign in as an organization **owner or admin**. Other roles do not see the page.
  </Step>

  <Step>
    Open **API Keys** in the sidebar, in the admin section next to Team Members and Subscription.
  </Step>

  <Step>
    Click **Create API Key** and give it a label, such as `Newsroom watch folder`. The label is only for you.
  </Step>

  <Step>
    Copy the key from the dialog and store it in a secret manager. &#x2A;*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.
  </Step>
</Steps>

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 [#use-a-key]

Send it as a bearer token on every request:

```bash
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 [#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 [#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 [#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 [#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.
