This article is auto-synced from its in-app version in Tai.
API keys and OAuth clients let external systems and applications call the TAI API on behalf of your company without a user login. They are administered by users with the Company Admin role from the Settings hub.
An API key is one secret value your integration sends with every request.
An OAuth client has a client ID and a client secret, which your integration exchanges for access tokens that expire after 15 minutes. It has no key value of its own.
Both carry the same access scope and restrictions. Not sure which to use? See Agent authentication.
When you'd use this
Create an API key or OAuth client when you want to invoke agents programmatically — for example, to call an agent from your own backend, a scheduled job, or an SDK integration. Each can be narrowed to specific permissions and optionally restricted to known IP addresses.
Steps
Create an API key or OAuth client
In the Workbench sidebar, click Settings.
Under Users & Access, click API Keys.
Click New API key or OAuth client in the top-right corner.
Under Type, choose API key or OAuth client. The type is fixed once created.
Fill in the rest of the form:
Name — a descriptive label (e.g.
Production integration).Allowed agents — the agents this key may invoke. At least one is required. There is deliberately no "all agents" option, so a key you create today cannot quietly pick up an agent you add later. Personal agents are not listed: API keys and OAuth clients can't call a personal agent, only Company and built-in agents. To make one callable, a Company Admin opens it and clicks Release to company.
Allowed channels — how the key may reach those agents: the REST API or Streaming API (chat sessions). Leave it empty to allow both.
Permissions — a picker of what the key may do (read agents, invoke agents, read reports, read report content). Leave it empty to grant the key's full permission set — a key can only ever be narrowed, never widened past what an API key is allowed to do.
Allowed IPs — comma-separated IP addresses or CIDR ranges that may use this key (optional).
Allowed Referers — comma-separated referer domains (optional, for browser-based integrations).
Expires at — an optional expiry date and time after which the key stops working.
Click Create API Key or Create OAuth Client.
Copy what is shown immediately — for an API key, the key; for an OAuth client, the client ID and the client secret. The key or secret is shown only once. Store it in a secrets manager or environment variable.
View, edit, or revoke an API key or OAuth client
In Settings → API Keys, click its name. The Type column tells API keys and OAuth clients apart.
The detail page shows the key prefix (for an OAuth client, the Client ID), status, restrictions, and dates. Three things are editable here, each saved on its own and each taking effect immediately:
Name — click Rename, type a new name, and save.
Access scope — the agents, channels, and permissions the key may use. Click Edit on that card, adjust the pickers, and save. A personal agent in the scope (for example, one returned to its owner after the key was created) is marked with a warning icon: the key can't call it, and saving the scope fails until you remove it or a Company Admin releases the agent with Release to company.
Restrictions — the Allowed IPs and Allowed Referers. Click Edit on that card and enter comma-separated values, or clear a field to lift that restriction entirely.
To stop it working, click Revoke Key (or Revoke Client) and confirm. Revocation is immediate and cannot be undone.
Editing never changes the key or the client secrets — your integration keeps working under the same credential.
Manage an OAuth client's secrets
An OAuth client gets its first client secret when you create it. Its detail page lists its secrets in the OAuth client secrets card, where you can add a second one to rotate. API keys have no client secrets.
In Settings → API Keys, click the OAuth client's name.
In the OAuth client secrets card, click Generate client secret.
Copy the secret immediately — it is shown once, and only Done closes the window. Store it in a secrets manager or environment variable.
Switch your integration to the new secret, then click Revoke next to the old one. A client can have two active secrets.
The list shows each secret by its beginning and end, when it was created and last used to request a token, and whether it is active or revoked. Revoking a secret stops the tokens issued with it within about a minute and cannot be undone. See the Agent REST API guide for how to request and use tokens.
Rotate a key
Rotating a key — replacing it with a fresh one, without re-typing its setup — uses Duplicate, available from two places: a Duplicate button on a key's detail page (shown for every status, so you can replace a suspended or expired key too), or a Duplicate from an existing key picker on the create page. An OAuth client can be duplicated the same way, though rotating its client secret (above) is usually enough.
Click Duplicate. This opens the create page, pre-filled from the source's type, allowed agents, allowed channels, permissions, and IP/referer restrictions.
Review the pre-filled form. The name defaults to a "Copy of…" version of the original so the two keys stay easy to tell apart; if the source key named an agent that's since been deleted or suspended, the form drops it and shows how many were dropped. A personal agent is dropped too, with its own message. Read any message about dropped permissions or channels carefully — leaving one out makes the new key less restricted, not more, so narrow it before you create. The expiry date is never carried over — set a fresh one if this key should also expire.
Click Create API Key (or Create OAuth Client) and copy the new secret immediately, as usual.
Update your integration to use the new key.
Once the new key is confirmed working, revoke the old one from its detail page.
Tips and limits
An OAuth client's Client ID is on its detail page. Your integration sends it with a client secret to
/api/v1/oauth/tokenand gets back a token that expires after 15 minutes. See the Agent REST API guide.The type is fixed. To move an integration from an API key to OAuth, create an OAuth client with the same scope, switch the integration over, then revoke the key.
The full key value is shown only at creation time. If you lose it, create a new key and revoke the old one.
Duplicate carries over the type and scope (agents, channels, permissions, IPs, referers) but never the expiry date, the key or any client secret — every copy gets its own fresh key or first client secret and, by default, no expiry.
A revoked key returns an authentication error within about a minute, usually at once.
Keys without an expiry date remain active until revoked.
Use the Allowed IPs restriction to limit a key to your server's egress addresses — this reduces risk if the key is accidentally leaked.
Allowed IPs accepts a bare IPv4/IPv6 address (e.g.
10.0.0.1) or a CIDR block (e.g.192.168.1.0/24). A range with host bits set (e.g.10.0.0.5/24) is rejected with the corrected form suggested.List the public egress address your integration connects from — that is the address the restriction is matched against. Headers your client sends, such as
X-Forwarded-For, are ignored.Give each integration its own key, scoped to just the agents it needs. A key outside its scope gets the same response as one naming an agent that doesn't exist, so a leaked key reveals nothing about the rest of your setup. The same holds for reading: a key lists and reads only the agents in its scope, and only the reports it created on them.
Choosing which agents a key may reach is choosing those agents' full capability set. Permissions control what the key may do — invoke an agent, read a report — not what an agent does once invoked: whatever skills, connectors and knowledge an allowed agent uses, the key reaches through it.
Related