API tokens let another system, script or integration work with your Structurell subscription without using a person's login. Each token belongs to the subscription you're working in, and can only do what you allow. You manage tokens on **Account → Organisation → API Tokens**.

## Before you start

- You need to be a subscription administrator, or have been given permission to manage subscription users. Otherwise you'll see "Subscription admin access required".
- Your package must include API access. If it doesn't, Structurell shows "This capability is not enabled for this account." See [Package and add-ons](/account-and-access/package-and-add-ons).
- You can only give a token access that you have yourself. Services and features you can't use don't appear in the list.

## Create a token

1. Go to **Account → Organisation → API Tokens**.
2. In **Create token**, enter a **Name** that tells you what the token is for, such as the system that will use it.
3. Under **Expiry**, leave **No expiry**, or choose **Expires at** and set an **Expiry date** and time in the future.
4. Choose a **Language**. This is the language Structurell uses for requests made with this token.
5. Under **Subscription permissions**, choose the access the token needs for each service. Select **Advanced** to set access feature by feature. The count above the list shows how many scopes you've selected, for example "12 scopes selected".
6. Select **Create**.

Give each token the least access it needs. Tokens with 20 or more scopes, or with full access, are flagged as **Broad access** in [Access review](/account-and-access/access-review).

## Copy the token straight away

After you select **Create**, Structurell shows **Token created** with the token value and the message "Copy this token now. It will not be shown again."

1. Select the copy button next to the **Token** field.
2. Paste the token into the other system's settings, or store it somewhere safe such as a password manager.
3. Select **Done**.

Once you select **Done**, the value can't be shown again. If you lose it, rotate the token or revoke it and create a new one.

## Review your tokens

**Existing tokens** lists every token for the subscription. Each one shows its name and language, when it was **Created**, when it **Expires** (or **No expiry**), its **Status**, and the **Services**, **Entities** and **Actions** it can use.

The status shows where each token is in its life:

- **Active** means the token works.
- **Awaiting First Use** means it's a replacement created by rotating another token, and hasn't been used yet.
- **Retiring** means it has been replaced, but the replacement hasn't been used yet, so this token still works.
- **Retired** means its replacement has been used, so this token no longer works.

A rotated token also shows which token replaced it, or which token it replaces.

## Edit a token

You can rename a token or change its access without issuing a new value, so the other system keeps working.

1. Select **Edit** next to the token.
2. In **Edit token**, change the **Name** or the **Subscription permissions**.
3. Select **Save**. You'll see "Token updated."

The change reaches the token within a minute. From then on, the token can only use access that you yourself hold. If you see **Permissions not shown**, Structurell can't display the token's current access: choose every permission it should have, because saving replaces what it has now.

You can't edit a token that has been replaced by a rotation.

## Rotate a token

Rotating creates a replacement token with the same access, so you can swap credentials without downtime.

1. Select **Rotate** next to the token.
2. Read "The current token will keep working until the replacement is first used, then it will be revoked." and select **Rotate token**.
3. Copy the new token from **Token created**, then select **Done**.
4. Update the other system to use the new token.

The old token stops working as soon as the new one is used for the first time. Expired tokens can't be rotated, and a token can only have one replacement at a time.

## Revoke a token

1. Select **Delete** next to the token.
2. Read "This token will stop working immediately." and select **Revoke token**.

If you delete a token that's part of an unfinished rotation, both the old and the new token are revoked. You'll see "Both credentials in this pending rotation will stop working immediately."

## Troubleshooting

- **"Enter a token name."** Give the token a name before you create it.
- **"Choose at least one scope."** Pick some access under **Subscription permissions**.
- **"Choose a future date."** The expiry must be later than now.
- **The permissions list is empty.** You don't have any access you can give to a token. Ask a subscription administrator.
- **Rotate is greyed out.** The token has expired, has already been replaced, or is a replacement that hasn't been used yet.
- **Edit is greyed out.** The token has been replaced by a rotation. Edit the replacement instead.
- **A system suddenly can't connect.** Check whether its token has expired, been revoked, or been retired by a rotation.

## Related articles

- [Access review](/account-and-access/access-review)
- [Users, teams, groups and permissions](/account-and-access/users-teams-groups-and-permissions)