API tokens
Create your own API token for the REST API and MCP, choose its Space, permission level and expiry, and rotate or revoke it. Space admins can revoke any token pointed at their Space.
An API token is the single credential behind both the REST API and MCP. You create tokens yourself inside BesTest, and you can rotate or revoke them at any time. There is no request form and no waiting on us.
There are two screens, and which one you want depends on what you are doing:
| Screen | Where | What it is for |
|---|---|---|
| API & MCP tokens | App menu (the hamburger), under Documentation | Your own tokens, across every Space. Create, rotate, revoke, delete. |
| API / MCP tab | Space settings | Every token pointed at this Space, whoever owns it. Space admins revoke from here. |
Create a token
- Open the app menu (the hamburger in the BesTest header) and choose API & MCP tokens. The modal lists every token you own, in every Space.
- Choose Create token.
- Give it a name. This is required, and it is the only thing you will have to recognise it by later, so name it after the job rather than after yourself.
nightly-playwright-uploadbeatsmy token. - Pick the Space the token may reach. One token reaches exactly one Space; if you automate two, create two tokens.
- Pick an expiry: 30, 60 or 90 days, one year, or a custom date. Every token expires, the maximum is one year, and there is no never-expires option.
- Pick an access level:
- Read only - the token can read everything you can read in that Space and change nothing. Right for dashboards, reports, release gates and most agent work.
- Read and write - the token can also create and update. Needed for pushing automated results, bulk imports and anything that edits.
- Choose Create token.
Copy the token now, because it is shown once
The moment a token is created, the full value is displayed with a copy button. That is the only time you will ever see it. Close the panel and it is gone for good: from then on the app only shows a masked form, the bst_pat_ prefix plus the last four characters, which is enough to tell two tokens apart and useless to anyone who steals it.
If you lose a token, you do not recover it. You rotate it, or you create a new one.
A BesTest token is a bearer credential: whoever holds it can act as you, within that one Space and at that permission level, until it expires or is revoked. Put it in your CI secret store, your password manager, or your agent's config file, and keep it out of source control, screenshots, and support tickets. If a token has leaked, revoke it first and ask questions afterwards.
Read a token's status
Both screens show a status derived from the token's dates, and the rules run in this order:
| Status | Meaning |
|---|---|
| Active | Working normally. |
| Expires in N days | Still working, but expiry is within 30 days. Time to plan a rotation. |
| Expired | Past its expiry date. Every request returns 401. |
| Revoked | Deliberately killed. Every request returns 401, permanently. |
Revoked wins over everything, so a token that was revoked and has since passed its expiry date still reads Revoked.
By default both tables show only live tokens. Turn on Show expired and revoked to see the dead ones, which are kept as a record of what existed.
Rotate a token
Rotating re-issues the token: a brand new value is generated and shown once, and the previous value stops working immediately. Nothing else changes, so the name, Space, access level and expiry stay as they were.
Rotate when a token is nearing expiry, when someone who had access has left, or when you suspect it has leaked.
Because the swap is instant and not staged, anything still using the old value breaks the moment you rotate. Have the new value ready to paste into your CI secret or agent config before you press the button, not after.
To rotate: open API & MCP tokens from the app menu, find the token, open its row menu, and choose Rotate.
Revoke a token
Revoking is a permanent kill. The token stops working immediately and cannot be brought back; if you need access again, you create a new token.
The revoked row stays in the list on purpose, as a record that the token existed and was killed. Once a token is revoked or expired, a Delete action appears that removes the row entirely.
As the owner: open API & MCP tokens from the app menu, find the token, open its row menu, and choose Revoke.
As a Space admin: open Space settings → API / MCP. That table lists every token pointed at this Space, whoever owns it, with the owner, name, access level, creation date, expiry, last use and status. Open the row menu on any live token and choose Revoke.
A Space admin can see and revoke every token aimed at their Space. That is the whole of it. An admin cannot create a token for somebody else, cannot rotate one, cannot reveal one, and cannot delete another person's row. Revocation is a safety valve, not a way to take over someone's access.
Use the token
Send it as a bearer token in the Authorization header, against your region's base URL:
curl "https://prod-eu.getbestest.com/api/v1/requirements" \
-H "Authorization: Bearer bst_pat_YOUR_TOKEN_HERE" \
-H "Accept: application/vnd.api+json"For an AI agent the same token goes in the client's config as an Authorization header. See Connect an MCP client.
When something returns 401
A 401 means the request was not authenticated. In rough order of likelihood:
- Wrong region. A token minted against the EU server does not work against the US or India server. Check the base URL against the region table.
- Expired. Check the status on the token screen.
- Revoked, by you or by a Space admin.
- Rotated, and the old value is still in your config.
- Malformed header. It must read
Authorization: Bearer <token>, with a single space and no quotes around the value.
A 403 is a different problem: the token authenticated fine but is not allowed to do that. Usually it is a read-only token attempting a write, or a request aimed at a Space the token does not reach.
Related
- Overview - regions, permissions and rate limits
- Connect an MCP client - where the token goes in each agent
- REST API - what you can call with it