Access tokens
Open in the interactive reference
There are two kinds of access token. A system access token, created on API Hub › Connect › Access Tokens, is for an integration you deploy. A personal access token is for developing and testing. A new token of either kind can call nothing until you grant it access.
A system access token does not act as you. Every system access token in your tenant acts as one shared system user, Integration System, which is not a person and cannot sign in. A personal access token acts as you.
Who can create tokens
Creating a system access token needs the permission Manage System Access Token Scope (API-HUB). The standard roles Integration Admin, All Applications Admin, All Applications Admin w/o HR and Accountant w/ Integration include it. The permission View System Access Token Scope (API-HUB) opens the Access Tokens page and each token's page without letting you change anything.
Creating a personal access token needs the permission Manage own Personal Access Tokens.
Creating a system access token
- Open API Hub › Connect › Access Tokens and select Create Token.
- Enter a Name. Names do not have to be unique, and you can change one later.
- To make the token work in a sandbox, select Restrict this token to a sandbox and choose the Sandbox Environment. Without it, the token works on your live data, and you cannot change that later.
- Choose an Expiration: 7, 30 or 90 days, or a custom date. 30 days is selected to start with.
- Select Create Token, then Copy Token, and store the value in a secret store. It is shown only this once.
- Select Close. The token's page opens, where you grant it access.
Granting access
On the token's page, select Manage Access, or Grant Access while the token has no access yet. In the dialog, choose an area in the tree on the left, or search for an area or an operation. Each area offers two kinds of grant:
- Broad Access grants the area as a whole, including operations added to it later, as in Accounting Customers: Read Access. Some top-level areas also offer one grant for everything in them, such as All Base Endpoints: Read Access.
- Specific Operations grants exactly the operations you select. Operations added to the area later are not included.
Grants add up: a specific operation never narrows a broad grant, so you can combine them, for example a broad read grant plus the one update operation an integration needs. Reading, writing and deleting are usually separate grants, so a token that can read a collection may still be refused when it writes to it.
Select Review Changes, then Confirm Changes, to save the grants. Save Changes on the token's page saves only its name and sandbox.
You can change a token's grants at any time, and the token keeps its value. A change can take up to five minutes to reach a token that is already in use. When a 403 is unexpected, check the token's grants before you change the request.
Production and sandboxes
A sandbox is a copy of your production data and settings. Use one to test changes, such as a new integration, without affecting production. To learn more, see Live Sandbox.
A token is bound when you create it, and the binding does not follow the sandbox you happen to be in. It is bound to production, your live data, unless you select Restrict this token to a sandbox and choose the sandbox yourself. It reads and writes only the data it is bound to. The token list shows a production token's scope as Main.
A sandbox token can be moved to another open sandbox, and stops working in the one it leaves. To move one, open its page while you are outside every sandbox, select Edit, choose the sandbox under Sandbox environment for API execution, and select Save Changes. A sandbox token can never be moved to production, and a production token can never be moved into a sandbox.
A sandbox token stops working when its sandbox is merged, closed, archived or deleted, or becomes inconsistent after a system upgrade. Merging or rebasing the sandbox does not move or revoke the token; a rebase creates a new sandbox, so move the token to it, or to another open sandbox, to keep using it. A sandbox cannot be deleted while system access tokens bound to it have not expired.
Checking a token
A token's page shows banners for anything that stops it working, and several can show at once. Check them first when a request is refused with 401 or 403.
| Banner | Meaning |
|---|---|
| Ready | The token is fully set up and can be used. |
| Expiring Soon | The token expires within the next 7 days. |
| Expired | The token has expired. |
| No Permissions | The token has not been granted any access yet. |
| Unconfigured Sandbox | The token is restricted to a sandbox, but no sandbox is set. |
| Inconsistent Sandbox | The token's sandbox is inconsistent. Rebase it, then move the token to the new sandbox the rebase creates. |
| Closed Sandbox | The token's sandbox was closed. |
Expiry, renewal and revocation
Every token has an expiry date. Its value is shown only once, when the token is created or renewed, so store it in a secret store straight away.
To renew a token, select Renew on its page and choose the replacement's expiry: 7, 30 or 90 days, or a custom date. The replacement has a new value and a new Token ID, and the same name, access and sandbox. The original is revoked at once, with no overlap. To change credentials without an interruption, create a second token where you created the first, grant it the same access, switch the integration over, and then revoke the first.
To revoke a system access token, select it in the list on the Access Tokens page and select Revoke Token. To revoke a personal access token, use the delete button on its row in the Personal Access Tokens list. Revoking deletes the token and cannot be undone.
A revoked token is refused from the next request on. For up to five minutes after revocation, that refusal can be a 500 rather than a 401.
Personal access tokens
A personal access token acts as you: it can do only what both its grants and your own permissions allow. It is convenient for testing.
- Open User Settings in Settings & Policies, and go to General › Security › Personal Access Tokens.
- Select Create.
- Under Token Page, choose Fine-grained (API Hub).
- Enter a Name. Sandbox Policy is set to Unrestricted, which works on your live data; choose Restricted and a sandbox to make the token work in a sandbox instead. Choose an Expiration; 7 days is selected to start with.
- Select Create Token, copy the value, and select Close. The token's page opens, where you grant it access with Manage Access, as for a system access token.
Personal access tokens are not listed on the Access Tokens page. Open one from the Personal Access Tokens list in User Settings.