# Access tokens

[Open in the interactive reference](https://docs.api.lensing.ai/guides/tokens)

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

1. Open **API Hub › Connect › Access Tokens** and select **Create Token**.
2. Enter a **Name**. Names do not have to be unique, and you can change one later.
3. 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.
4. Choose an **Expiration**: 7, 30 or 90 days, or a custom date. 30 days is selected to start with.
5. Select **Create Token**, then **Copy Token**, and store the value in a secret store. It is shown only this once.
6. 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](https://lensing.ai/product/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.

1. Open **User Settings** in Settings & Policies, and go to **General › Security › Personal Access Tokens**.
2. Select **Create**.
3. Under **Token Page**, choose **Fine-grained (API Hub)**.
4. 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.
5. 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.