Structurell Help

Article

API tokens

Create, scope, edit, rotate and revoke tokens that let other systems use the Structurell API for your subscription.

Updated

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.
  • 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.

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

View this article as Markdown