# Authentication

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

1. Log in to Avallone as an admin.
2. Go to **Settings → Users**.
3. Create or select an API user.
4. 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.
5. Copy the token.

## Send the token

Include the token in every request:

```http
Authorization: Bearer <your-token>
```

For example:

```bash
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:

1. Create a new token.
2. Switch your integration to the new token.
3. 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.