Skip to main content
Use a personal API key to authenticate requests from your server or integration. Create and manage these keys in the dashboard, then send the secret in the x-api-key header. Give each deployed service its own key so you can replace or revoke it independently.
Recording pending for Create, rotate, and revoke an API key. No playable video is available yet.

Recording pending: Create, rotate, and revoke an API key. Follow the written guide below.

​
Before you begin

Sign in to the workspace your integration should use. You need permission to create personal API keys and access to the operations you intend to grant. Have a server-side secret manager or environment variable ready to store the new secret.

​
Create a key

1

Open API keys

Open Developers > API Keys, then select Create key.
2

Name and scope the key

Use a name that identifies the service and environment, such as Support integration staging. Keep Restrict key enabled and select only the available permissions your integration needs.Write access includes read access for the same API area. The permission choices are limited by what your own account can grant.
3

Choose expiry and IP restrictions

Set Expire after to match the integration’s lifetime and your rotation policy. If requests come from known outbound addresses, enable Restrict by IP address and enter those addresses or CIDR ranges.
4

Create and store the secret

Select Create key, then copy the secret from the confirmation dialog before closing it. Save it in your server-side secret store. The key list does not reveal the complete secret again.
5

Verify a permitted request

Follow the authentication examples to send x-api-key. Choose a read operation covered by the key’s permissions and confirm that the response belongs to the intended workspace.
Screenshot pending for API-key metadata list with names and permissions, with every secret hidden. This illustration is not a product screenshot.

Screenshot pending: API-key metadata list with names and permissions, with every secret hidden.

The key should appear in your API-key list, and a permitted request should authenticate successfully. This verifies the key’s access to that operation; it does not confirm that an agent or external integration has executed.
Never put an API key in a browser bundle, URL, public repository, screenshot, recording, log, or support message. Do not send both x-api-key and Authorization in one request.

​
Replace or revoke a key

For a planned rotation, create a replacement key with the required permissions. Update every service that uses the old key, verify its requests, then use the old key’s Revoke action and confirm Revoke key. If a secret may have been exposed, revoke it immediately and replace it in the affected services. A revoked key must no longer be used for requests. Review a key’s permissions, expiry, and IP restrictions when an integration changes. Editing permissions can produce a replacement secret. If the dashboard shows a new secret, save it and update the integration before closing the dialog.

​
Personal keys and service accounts

Personal key creation and management use the Threetone dashboard. The public API reference is not a separate personal-key creation workflow. Service accounts and their API-key operations are currently unavailable. Their reference endpoints are present, but they return HTTP 501. Use a permitted personal key for the workflow described here. See Create workspace service account for the reserved operation’s schema.

​
Troubleshooting

Keep the response’s X-Request-Id when requesting help, and remove the key from any shared evidence. The authentication guide covers header examples and credential errors.

​
Frequently asked questions

The list does not reveal the full secret again. Create a replacement if the secret was not stored.
Create the replacement, update the integration, verify permitted requests, then revoke the old key. If it was exposed, revoke it promptly.
The documented service-account operations remain unavailable. Use the supported personal-key workflow with the required permissions.