Get a token
When the token expires, exchange the secret again. There is no refresh token.
Send the token
Put the token in theAuthorization header of every request:
When authentication fails
A key’s creator can no longer act when their account was deactivated or deleted, or when they left the organization the key belongs to. Their keys stop issuing tokens, and tokens already issued stop working within seconds.
Who may use API keys
- Enterprise: Admins create and manage keys.
- SaaS: keys are part of the Pro and Business plans. Members create and see their own keys; on Business an Admin sees every key of the organization. On the Free plan, creating a key and every call made with one answer
403withAPI keys are not available on the Free plan. Upgrade your plan to use them.A key made on a paid plan stops working if the account moves to Free.
Permissions
A key reaches only what its permissions open. A call outside them answers403 with API key doesn't have required permissions: […]. A key with Admin passes every permission check.
Each operation in the Endpoints section names the permission it needs.
What a key cannot do
Some endpoints are for signed-in people only and refuse a key:
Workflow schedules are open to a key with Agents.
What a key can reach
A key acts inside a scope:- Enterprise: an organization’s key reaches the agents and runs of that organization.
- SaaS: a key sees the agents and other resources that the person who created it sees. Runs are the exception: a key of a Business organization can read, stream and cancel every run of that organization, whoever started it.
- A key with no organization (one made on a SaaS personal account) reaches only what its creator made, and never the administration of users and groups, whatever its permissions.
403.
Who a key’s work counts against
The runs a key starts count against the person who created it: their limit of runs at the same time and, on SaaS, their plan’s usage. Settingname or email on POST /chat does not change that; those fields only label the turn in Interactions, where the key’s work shows under the key’s name.
Related
- API keys: create, turn off and delete keys in the web app
- Your first API call
- Errors