> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API keys
> Create, scope, use, rotate, and revoke the personal rma_ keys that authenticate every Managed Agents API request.
An API key lets your code, scripts, and coding agents call the Managed Agents API as you. Each key is personal, expires, and is scoped to your whole tenant or to one organization.
## Before you begin
* You need a role with Managed Agents access to see **API keys** in the console. See [Organizations and roles](/managed-agents/organizations-and-roles).
* Keys are created and revoked only in the console, while you're signed in. An API key can't create or revoke keys.
## How keys work
* **A key acts as you.** Requests run with the role you hold in the target organization, checked on every request.
* **The secret is shown once.** A key starts with `rma_`. After you close the drawer, only a hint such as `rma_…a1b2` is shown, and the full key can't be retrieved.
* **Every key expires.** Choose a lifetime of up to 365 days. There's no "never expires".
* **Keys are yours alone.** The list shows only the keys you created, and you're the only one who can revoke them.
## Choose a scope
| | Organization scope | Tenant scope |
| -------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------ |
| In the console | **Scope** set to an organization, such as **Default**. | **Scope** set to **Tenant**, which is the default choice. |
| Where it works | One organization. | Any organization in the tenant that you can reach. |
| `x-organization-id` header | Not needed. If you send it, it must name the key's organization. | Required on every request: an organization id, or `default`. |
Your tenant has one organization, **Default**, so both scopes reach the same resources. Prefer organization scope: it needs no extra header.
## Create a key
1. Open the [Recursion console](https://recursion.labelbox.com). In the sidebar, click **API keys**, then **Create key**.
2. Enter a **Name** that says where the key is used, such as `nightly-report-prod`.
3. Choose a lifetime in **Expires**: 3 hours, 1 day, 7 days, 30 days, 90 days, or **Custom date** up to one year out. The default is 30 days.
4. **Linked account** shows you. Requests with this key act as you.
5. Choose the **Scope**: **Tenant**, or one organization, such as **Default**. It starts on **Tenant**.
6. Click **Create key**.
7. On **Save your API key**, copy the key and store it in a secret manager. This is the only time it's shown.
A custom date expires at the end of that day in your local time, or one year from now if that comes first.
## Use a key
Send the key as a bearer token. An organization-scoped key needs nothing else. A tenant-scoped key also sends `x-organization-id`.
```typescript theme={"theme":"css-variables"}
import { createRecursionClient } from '@labelbox/recursion-sdk';
const rl = createRecursionClient({
apiKey: process.env.RECURSION_API_KEY!,
baseUrl: 'https://api.recursion.labelbox.com',
// Tenant-scoped keys only:
headers: { 'x-organization-id': 'default' },
});
const { items } = await rl.managedAgents.listModels({});
```
```bash theme={"theme":"css-variables"}
# Omit the x-organization-id line for an organization-scoped key.
curl 'https://api.recursion.labelbox.com/managed-agents/v1/models' \
-H "Authorization: Bearer $RECURSION_API_KEY" \
-H 'x-organization-id: default'
```
Once a request reaches an organization, its response includes `recursion-organization-id` and `recursion-tenant-id` headers, so you can confirm which organization it ran in.
## Key statuses
| Status | Meaning | Can you revoke it? |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| **Active** | The key works. | Yes. |
| **Inactive** | The key is neither expired nor revoked, but your account no longer reaches its tenant or organization, so it doesn't work. | Yes. |
| **Expired** | The key reached its expiry date. | No. |
| **Revoked** | You revoked the key. | No. |
Filter the list by **Status** and **Scope** to find a key.
## Revoke a key
1. In **API keys**, open the actions menu on the key's row.
2. Click **Revoke**, then **Revoke key**.
The key stops working immediately. Revoking can't be undone.
## Rotate a key
Rotate before a key expires, or right away if it might have leaked.
1. Create a new key with the same scope.
2. Deploy it to the service that uses the old key.
3. Confirm the service works with the new key.
4. Revoke the old key.
## Keep keys safe
* Store keys in a secret manager or your platform's secret store. Load them into an environment variable such as `RECURSION_API_KEY` at run time.
* Never commit a key, put it in a system prompt or session message, or paste it into a chat with an AI assistant.
* Use one key per service or coding agent, so you can revoke one without breaking the others.
* Choose the shortest expiry that works. Short-lived keys limit the damage of a leak.
* Never give a key to an agent running inside Recursion. To give an agent credentials, use a [vault](/managed-agents/vaults).
## What a key can't do
A key only calls Managed Agents operations. It can't create, list, or revoke API keys.
## What can go wrong
| Code or symptom | Cause | Fix |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| `401 unauthorized` | The key is missing, mistyped, expired, revoked, or inactive. | Check the `Authorization` header and the key's status. Create a new key if needed. |
| `400 invalid_request` mentioning `x-organization-id` | A tenant-scoped key sent no `x-organization-id`, or the header isn't an organization id or `default`. | Send `x-organization-id: default`, or use an organization-scoped key. |
| `404 not_found` on every request | `x-organization-id` names an organization you can't reach, or a different organization than the key's. | Send `default`, or omit the header for an organization-scoped key. |
| The key worked yesterday and doesn't today | It expired or was revoked. | Check its status under **API keys**, then create a new key. |
| **Create key** stays disabled | **Name** is empty, or **Custom date** is empty or in the past. | Enter a name, and choose a date between tomorrow and one year from today. |
## Limits
| Limit | Value |
| ------------ | -------------- |
| Key name | 100 characters |
| Key lifetime | 365 days |
See [Limits](/managed-agents/limits) for every other limit.
## Next steps
Set up a client and learn the request rules.
See what each role can do with a key.
Give a coding agent a key safely.
See how credentials and data are protected.