Authentication
How to get an API token, send it with each request, and rotate it.
Every request to the Avallone API needs a token. A token belongs to an API user in your tenant, and it is sent as a Bearer token in the Authorization header.
Get a token
- Log in to Avallone as an admin.
- Go to Settings → Users.
- Create or select an API user.
- Add a token. Give it a name that says where it will be used. It expires after 1 year by default, or you can choose an expiry from 3 months to 3 years.
- Copy the token.
Send the token
Include the token in every request:
Authorization: Bearer <your-token>For example:
curl https://api.avallone.io/api/v1/companies/by-ref/acme-inc \
-H "Authorization: Bearer eyJhbGc..."When a request is refused
| Status | Why |
|---|---|
401 | The token is missing, malformed, expired or revoked. |
403 | The token is valid, but it lacks the permission the endpoint needs, or its API user is deactivated. |
Each endpoint's page names the permission it needs.
Permissions
A token's permissions are set when the token is created. They are copied from your tenant's default API permission group.
Changing that group doesn't change tokens that already exist:
- To give an integration a new permission, add it to the group, create a new token, and switch your integration to it.
- To take a permission away, remove it from the group, then create new tokens and revoke the old ones.
Rotate a token
An API user can have several active tokens. To replace one without downtime:
- Create a new token.
- Switch your integration to the new token.
- Revoke the old token. In Avallone, this is the Deactivate action on the token.
A revoked token stops working at once.
Rotate tokens before they expire. Rotate a token straight away if it may have leaked.
Keep tokens safe
- Treat a token like a password. Don't commit it to source control.
- Inject it at runtime from an environment variable or a secrets manager.
- Use one token per integration, so you can revoke one without affecting the others.