API keys

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.
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

Console

Open the Recursion console. In the sidebar, click API keys, then Create key.
Enter a Name that says where the key is used, such as nightly-report-prod.
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.
Linked account shows you. Requests with this key act as you.
Choose the Scope: Tenant, or one organization, such as Default. It starts on Tenant.
Click Create key.
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
cURL

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({});

# 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

Console

In API keys, open the actions menu on the key’s row.
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.

Create a new key with the same scope.
Deploy it to the service that uses the old key.
Confirm the service works with the new key.
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.

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 for every other limit.

Next steps

API conventions

Set up a client and learn the request rules.

Organizations and roles

See what each role can do with a key.

Connect a coding agent

Give a coding agent a key safely.

Security

See how credentials and data are protected.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Before you begin

How keys work

Choose a scope

Create a key

Use a key

Key statuses

Revoke a key

Rotate a key

Keep keys safe

What a key can’t do

What can go wrong

Limits

Next steps

API conventions

Organizations and roles

Connect a coding agent

Security

​Before you begin

​How keys work

​Choose a scope

​Create a key

​Use a key

​Key statuses

​Revoke a key

​Rotate a key

​Keep keys safe

​What a key can’t do

​What can go wrong

​Limits

​Next steps

API conventions

Organizations and roles

Connect a coding agent

Security

Before you begin

How keys work

Choose a scope

Create a key

Use a key

Key statuses

Revoke a key

Rotate a key

Keep keys safe

What a key can’t do

What can go wrong

Limits

Next steps