> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twine.se/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Provision access tokens and authenticate against the Twine Public API

The Twine Public API uses Bearer token authentication. Send the token in the `Authorization` header with the value `Bearer <token>`:

```bash theme={null}
Authorization: Bearer <token>
```

## Provisioning a token

Access tokens are short-lived and are generated from a long-lived **refresh token**. Generate the refresh token in Twine backoffice first, then exchange it for access tokens as needed.

<Warning>
  Keep the refresh token secret and never share it. It can be used to mint access tokens for the API.
</Warning>

To obtain an access token:

<Steps>
  <Step title="Begin the exchange">
    Invoke `/provisioning/refresh-token/begin` using the JTI you received when provisioning the refresh token.
  </Step>

  <Step title="Read the salt">
    The response contains a `salt` value.
  </Step>

  <Step title="Build the signature input">
    Concatenate the salt with the refresh token, separated by a colon (`:`).
  </Step>

  <Step title="Hash it">
    Hash the concatenated string using SHA256, for example `sha256 "<salt>:<refresh_token>"`. The hash must be in lower case.
  </Step>

  <Step title="Refresh">
    Invoke `/provisioning/refresh-token/refresh` with the JTI (as `jti`) and the hash (as `signature`) in the body.
  </Step>

  <Step title="Receive the access token">
    The response contains an access token.
  </Step>
</Steps>

## Legacy tokens

Legacy tokens are still supported. These tokens are long-lived and can be used to authenticate against the API. The token provisioning system above is recommended for new integrations.

## Token expiration

Provisioned tokens are short-lived. Decode a token to find its expiry time. Legacy tokens have longer expiry times.

## Permissions

All API requests are subject to a permissions check. Permissions are configured by Twine staff or an approved external admin.