Skip to main content
Choose a credential by where the request comes from:

​
API keys

Send an API key as a bearer token:
The organization API token (Settings → Organization → General → API Token) works only with the v1 API. The Trunk Analytics CLI and trunk-io/analytics-uploader don’t accept API keys yet, so keep using the organization API token with them.
Keys belong to the organization, so they keep working after their creator leaves. There’s no limit on how many you create. Give each integration its own key, with only the permissions it uses. Separate keys don’t get separate limits. Most requests share one organization-wide limit, so one busy key can push every other integration into 429s. See Rate limits.

​
Create an API key

Only an organization admin can create an API key. In the Trunk app:
  1. Navigate to Settings → Developer → API Keys and click the Create Key button.
  2. Name the key after what will use it, such as ci-submit or grafana. Names must be unique among your organization’s active keys.
  3. Select the permissions the key needs. None are selected by default.
  4. Copy the key and store it in your secret manager. The key is shown only once. If you lose it, delete it and create a new one.
Keys start with trunk_v2_, so you can add that prefix to your secret scanner. To trace a leaked value to its key, match its first characters in the API Keys list, which also shows who created each key.

​
Permissions

Every key can read your organization’s merge queues, so a dashboard or Prometheus scrape needs no permissions. Each permission below adds writes: A request’s permissions come from its body as well as its endpoint. For example, a submit that sets a priority needs both Merge and cancel PRs and Set priority on PRs. A request that the key isn’t permitted to make returns 403 INSUFFICIENT_PERMISSIONS and changes nothing.
Permissions apply only to merge queues and test-results uploads. Any API key can call the other Flaky Tests and Dynamic CI endpoints, including writes.

​
Change or delete a key

An organization admin manages keys in the same API Keys list.
  • To change a key’s permissions, open the key and edit them. Its value stays the same, and the change applies within a minute.
  • To delete a leaked or unused key, open the key’s menu and click Delete. Deletion takes effect on the next request. Deleting can’t be undone.
To rotate a key, create its replacement and deploy it. Last use is updated at most once an hour, so it can trail a key’s real last use by up to an hour. Once the old key’s last-used time in the API Keys list has stopped advancing for over an hour, delete it.

​
GitHub Actions

A GitHub Actions job can upload impacted targets without an API key. The trunk-io/login action exchanges the run’s GitHub credential for a short-lived Trunk login, which can upload impacted targets for that repository and nothing else. See Upload impacted targets from GitHub Actions for setup, forks, and security.

​
The x-trunk-token header

Endpoint pages also list x-trunk-token. This header carries a short-lived Trunk login that Trunk’s own tools use: the trunk CLI after trunk auth login, and trunk-io/login. Use an API key instead, and never send both headers on one request.

​
Authentication errors

Trunk checks credentials at its edge, so authentication failures may lack the API’s error envelope. Branch on the status code. Endpoint pages may show 401 with the codes AUTHENTICATION_REQUIRED or INVALID_TOKEN in the envelope. Treat those as examples of the status, not as the body you’ll always receive.