Skip to main content
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.
You need a role with Managed Agents access to see Settings › API keys in the console. See Organizations and roles. Keys are created and revoked only in the console, while you’re signed in. A key only calls Managed Agents operations: it can’t create, list, or revoke API keys.

​
Choose a scope

Prefer organization scope: it reaches only one organization and needs no extra header. Use tenant scope when one key must work in several organizations. See Organizations and roles.

​
Create a key

  1. Open the Recursion console. In the sidebar, click Settings, choose API keys, then click 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, and the key stops working if you lose access to its organizations.
  5. Choose the Scope: one organization, such as Default, or Tenant. It starts on the organization you’re in.
  6. Click Create key.
  7. On Save your API key, click Copy key and store the key in a secret manager. This is the only time it’s shown.
  8. To use the key from your own computer, choose your operating system under Save it as RECURSION_API_KEY, copy the command, and run it in a terminal. It saves the key for every new terminal: in ~/.zshrc on macOS, in ~/.bashrc on Linux, or in your user environment on Windows.
  9. Close the drawer. If you haven’t copied the key or a command, the console asks before it closes.
The 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. 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.
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.

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

​
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. You can revoke an Active or Inactive key.
Filter the list by Status and Scope to find a key.

​
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. Store it when you create the key; it can’t be retrieved later.
  • 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.

​
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.
  • Run the console’s RECURSION_API_KEY command only on your own computer. It writes the key to your shell profile or your Windows user environment, and the command stays in your shell history, so don’t run it on a shared machine or a server.
  • 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 can go wrong

The most common problems:
  • 401 unauthorized. The key is missing, mistyped, expired, revoked, or inactive. Check the Authorization header and the key’s status, and 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.
Key name and lifetime limits are in Limits.

​
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 to the Recursion MCP

Use your key with the authenticated MCP endpoint and give a coding agent a key safely.

Security

See how credentials and data are protected.