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 a key before it expires, when someone who had it leaves, or right away if it might have leaked. Rotating gives you a new key with the same name, scope and linked account, and keeps the old key working for a while so you can switch without downtime.
  1. In API keys, open the actions menu on an Active key’s row and click Rotate.
  2. Under Keep the old key working, choose how long the old key keeps working beside the new one: Stop it now, 1 hour, 24 hours, 3 days or 7 days. The default is 24 hours. Choose Stop it now if the key might have leaked.
  3. Click Rotate key.
  4. On Save your API key, click Copy key and store the new key in your secret manager. This is the only time it’s shown.
  5. Deploy the new key to the service that uses the old one, and confirm it works.
The new key lasts as long as the old key was created to last, starting now. Until the old key stops, the list shows when it stops and which key replaced it, such as Stops working in 23 hours · replaced by rma_…9f3c. When its Last used time stops changing, nothing uses it anymore: revoke it early from its actions menu, or let it expire. The old key keeps its own expiry if that comes first. A key can be rotated only once; to rotate again, rotate its replacement. You can rotate your own keys, and admins and owners who manage service accounts can rotate a service account’s keys, also from the service account’s page. No one can rotate another person’s key, because rotating hands over a working key; an admin can revoke it instead. Organization admins can rotate their own keys scoped to an organization from that organization’s page. If your connection drops while rotating, click Try again. The console resends the same request, so you get the new key without creating a second one.

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. Each key also shows Last used: when it last authenticated a request, to within a few minutes, or Never.

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”.
  • Rotation keeps you running. A rotated key keeps working for the overlap you choose, up to 7 days, so you can deploy its replacement first.
  • Admins can see and revoke every key. Tenant admins and owners see every key in the tenant, who created each, and can revoke any of them, for example a key that leaked or one left behind by someone who left. Organization admins see the keys that act in their organizations and revoke those scoped to them. Everyone else sees only the keys they created.

See and revoke every key in your tenant

Admins and owners see every key in Settings › API keys, with a Created by column. Filter by Created by, Type (personal or service account), Status and Scope to find a key, then revoke it from its actions menu. The key stops working immediately for anything that uses it.

Find a leaked key

If you find a key somewhere it shouldn’t be, such as a repository, a log or a chat, admins and owners can find out which key it is. In Settings › API keys, click Find a leaked key and paste the secret. Recursion checks it against your tenant’s keys only and never stores or logs it. If it matches, you see the key, who created it, its scope, its status, when it was last used and, if it was rotated, the key that replaced it, and can revoke it there. A secret that isn’t one of your tenant’s keys shows no match.

Delete a member’s keys when you remove them

When you remove a member on Members, the confirmation lists the API keys that act as them, with Also delete their API keys ticked. Leave it ticked to delete those keys along with the removal: they stop working for good, stay deleted if the person is added back, and no longer appear in the list. Untick it to keep the keys: they stay inactive while the person isn’t a member, and start working again if they’re added back. Keys for a service account that the person created are never deleted, because they act as the service account. When you leave a tenant yourself, you’re offered the same choice for your own keys. Removing someone from one organization works the same way for their keys for that organization. On the organization’s Members, the confirmation lists their personal keys for it, with Also delete their API keys for the organization ticked. Leave it ticked to delete those keys along with the removal. Untick it to keep them: they stay inactive, and start working again if the person is added back to the organization. Their tenant-wide keys and their keys for other organizations stay as they are. Only the organization’s admins see this choice. When you leave an organization yourself, you’re offered the same choice for your own keys for it.

See and revoke an organization’s keys

Organization admins manage the keys of the organizations they administer. Tenant admins and owners are organization admins everywhere.
  1. In Settings › Organizations, open the organization.
  2. Under API keys, find the key. The list shows the keys scoped to this organization, and the tenant-wide keys of the people who can use it, with who created each. Filter by Scope and Status to narrow it.
  3. For a key scoped to this organization, open its actions menu, click Revoke, then Revoke key.
A tenant-wide key also works in other organizations, so it’s listed as Tenant-wide and only a tenant admin can revoke it, from Settings › API keys. An archived organization shows no keys.

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.