Create an API key for an external tool

Make a workspace API key so an MCP client or a script can read the work your workspace has published.

You want a tool outside TalentOS, usually an MCP client or a script, to read what your workspace has published. An API key is how you hand it that access. This page covers making one, what it can reach, and turning it off.

Any admin can do this. Members do not see the panel.

Create a key

Open Settings in the console and choose the API & MCP tab. (An older /admin/api-keys link redirects here.)
Select Create key.
Name it after the tool that will hold it, for example Ops reporting client. Up to 100 characters.
Select Create key. The full key appears once and starts with tos_.
Paste it straight into the tool, then close the dialog.

The full key is shown once, at creation. TalentOS keeps only a secured hash of it, so nobody, including support, can read it back to you. If you lose it, revoke that key and create another.

What a key can and cannot reach

A key is workspace-wide and unscoped. There is no way to limit one to a single Skill, a single connector, or a single person's chat, so treat it like a password for everything your workspace has published.

It reads the work your workspace has published, plus any drafts belonging to the person who created the key.
It never publishes and never changes anything already published. A key cannot edit shared work, cannot touch another member's private work, and cannot reach another workspace.
Because reads follow the person who created the key, a key made by someone with narrow visibility sees less. Create it as the person whose view the tool should have.
Each key is capped at 60 requests per minute.

Most tools reach the workspace through the TalentOS MCP server, which already knows the address to call. See Connect an MCP client. If you need to call the HTTP endpoints directly instead, write to support@talentos.so for the base address and the current endpoint list.

Rotate or revoke a key

The list shows every key with its name, the first eight characters of the key, when it was created, when it was last used, and whether it is Active or Revoked.

To rotate: create the replacement key first, paste it into the tool, confirm the tool still works, then revoke the old one. To retire a key outright, select Revoke on its row and confirm.

Revoking takes effect immediately and cannot be undone. Revoked keys stay in the list, greyed out, so you keep the record of what existed.

A workspace can hold 100 keys. Revoke the ones you no longer use rather than collecting them.

A worked example

An operations lead creates a key named Weekly reporting client, pastes it into the client's environment, and confirms the client can list the workspace's published Skills. They then create a replacement key, update the client, test one read, and revoke the old key. The revoked key stays listed for the audit record but stops working immediately.

What to check

401 Unauthorized. The same 401 is returned for a missing, malformed, unknown, or revoked key, on purpose. Check the header reads Authorization: Bearer tos_..., that you pasted the whole key, and that the key still shows Active.
429 Too Many Requests. You crossed 60 requests a minute on that key. The response carries a Retry-After value in seconds. Wait it out, or give the noisy tool its own key so it cannot starve the others.
"Last used" still says Never. That stamp is refreshed at most once an hour, so a key that just worked can still read Never for a while.
No API & MCP tab. You are signed in as a member. Ask an admin.