API access tokens

Every public API call is signed in with an API access token. An administrator generates the token on a user’s profile, and the integration then acts as that user. This page shows you how to generate a token, how long it lasts, and how to replace it.

Before you begin

• Complete edition. The API Access Token section only appears when your edition includes the public API.
• Permission to edit users. You generate tokens from a user’s profile, so you need access to Users → User. See Managing users.
• The user must have accepted their invitation. You can’t generate a token for a user who is still pending.
• You can’t hand out more access than you have. You can only generate a token for a user whose rights don’t exceed your own.

Tip

Create a dedicated user just for your integration (for example, “ERP Integration”) and give it Application Admin rights. The token then has full access to every API function, and the integration keeps working when people change roles or leave the company.

Generate a token

1. Open Users → User and click the name of the user the integration will act as.
2. Scroll to the API Access Token section and tick Make user an API user to generate an access token.
3. Pick the API Token Expiration Date (and time) with the calendar. The token stops working after this date.
4. Click Generate Token.
5. The token appears in the API Access Token box and is downloaded to your computer as a file. Store it somewhere secure, such as your organization’s password manager or secrets vault.

Caution

Save the token before you leave the page. Wasp Asset doesn’t store a copy you can view later, so once you navigate away the token can’t be shown again. If you lose it, generate a new one.

Replace (rotate) a token

Generate a new token the same way. If the user already has a valid token, Wasp Asset tells you when the last one was issued and asks you to confirm. Click Generate Token to continue.

Generating a new token permanently disables every earlier token for that user, so update your integration with the new token straight away. Rotate the token:

• Before the expiration date you chose, so your integration doesn’t stop unexpectedly.
• Immediately, if you think the token has been exposed (for example, pasted in an email or committed to source control).

Things that stop a token working

• The expiration date passes. Generate a new token with a later date.
• A newer token is generated for the same user. Only the latest token works.
• The user is disabled. Disabling the user disables their token too, and every API call fails until the user is enabled again.
• The user’s role changes. Calls are checked against the user’s current role, so removing permissions can make calls that used to work start failing. Keep integration users in an administrator role and leave it unchanged.

On-premises

You can’t generate a token for the built-in admin account that comes with an on-premises installation. Create a separate user for your integration and generate the token for that user.

Use the token

Send the token in the Authorization header of every request, after the word Bearer and a single space:

Authorization: Bearer <your token>

See the Public API overview for the other headers every request needs, or Try the API with Postman to test the token.

Related

• Public API overview — how calls are addressed and what they can do
• Managing users — create the user the integration acts as
• Roles & permissions — control what a token’s user can do