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”.
  • 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 and its status, 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.

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