API keys

Create an API key when a script or service needs to call Tale's REST API. A key belongs to the person who created it, not to the organization whose settings page created it: it acts as that person, follows their current permissions, and works in every organization they are a member of. A REST call names the organization it addresses with the X-Organization-Slug header; a key whose holder belongs to one organization may omit it. Owners, Admins, and Developers manage their keys under Settings > API > REST.

Create a key

1. Select Create API key.
2. Enter a Key name that identifies the caller, such as Billing sync or Document import.
3. Choose Expiration: 7, 30, or 90 days, one year, or never. The form starts at 30 days.
4. Create the key and copy its secret into the caller's approved secret store before closing the confirmation.

The complete secret is shown once. The table later shows only a masked fragment, the creation date, and when the key was last used. It lists your keys, not your teammates' keys.

Verify the caller

Follow the authenticated request in the API quickstart. Confirm the returned identity and organization before starting a write or import. After an authenticated request, check Last used in the key table.

A successful authentication does not guarantee permission for every resource. Project access and the key owner's current role still apply. If a request fails, use the API's error response to distinguish an expired or revoked key from missing resource permissions.

Rotate without an outage

1. Create a replacement key before the old one expires.
2. Update the caller's secret store and restart or reload it as its configuration requires.
3. Run an authenticated request with the replacement and check that it works.
4. Revoke the old key only after every dependent caller has moved.

Tale does not automatically rotate keys. Key creation and revocation happen in this UI, not through /api/v1. A caller can inspect its key's name and expiry through GET /api/v1/me and alert the responsible person before expiration.

Revoke a key

Open its row menu, select Revoke key, and confirm. Future requests with the key can no longer authenticate. Revocation cannot be undone; create a new key if you revoke the wrong one. Creating and revoking a key each leave a row in the audit log under Settings > Governance > Logs, in every organization you belong to.

Do not use an old Last used date as the only reason to revoke a key. A monthly job or a recovery process may legitimately be idle. Check the caller identified by the name first.

Understand permissions and limits

Role changes take effect for existing keys on subsequent requests. Disabling the owner's membership removes their access; a key does not preserve the role it had when created.

Give an integration the narrowest access that works. A notification mirror, for example, does not need an Admin account: an Admin can grant an ordinary member the tale:notifications.export capability, which permits that export and none of the other rights of the Admin role. The grant applies only in that organization, can expire, and ends when the member is removed. Grant it under Competences, where an integration that relays people's answers and review decisions gets tale:rest.act-as the same way; Delegate the export without an Admin role covers the API side.

REST rate limits apply to the authenticated key holder. Several keys owned by the same person do not provide separate rate-limit allowances. See Rate limits. A budget rule can additionally cap what requests authenticated with one key may spend: their usage counts toward the key, and a send over the cap is refused with 429 BUDGET_EXCEEDED. Automation runs started with the key count toward it as well, alongside the personal limits of the member the key acts for. How usage is counted has the full rule.

API keys authenticate software calling Tale. Connector credentials serve the other direction: they let Tale call an external service. Use Tale from your editor or a script shows where a key goes in opencode, Claude Code, and a shell script.