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

# Authentication

> Authenticate to the Brale API using OAuth2 client credentials to obtain short-lived bearer tokens.

The Brale API uses Bearer Authentication and API keys to authenticate your requests. Tokens are short-lived (\~60 minutes); refresh automatically using `expires_in`.

## API Keys

Your ability to authenticate to the API is granted through an API Key associated with an Application. Applications are specific to testnet or mainnet access, and have a specific set of permissions. You can create multiple API applications within the dashboard, each assigned specific API scopes.

## Create API Credentials

Create an application on the Settings page in the Dashboard. Brale will make your API key available only once. Please save the key in a secure location.

<img src="https://mintcdn.com/brale/BPXdiJ8ZrIJOuZ2b/images/brale/settings-api-credentials-dark@2x.png?fit=max&auto=format&n=BPXdiJ8ZrIJOuZ2b&q=85&s=fd19384fafa0c8f09bf955b8d289f763" alt="Image" width="1928" height="1056" data-path="images/brale/settings-api-credentials-dark@2x.png" />

## Obtain an Access Token

Brale uses OAuth2 with the `client_credentials` grant type for secure access to our APIs. Sending a request to the Auth endpoint will return a bearer token to be used on all subsequent calls. The response will include the number of remaining seconds that the token is valid before a new one will need to be retrieved.

The Authorization header uses Basic HTTP Authentication. This requires encoding your `client_id` and `client_secret` into a Base64 format.

To generate the Base64 encoded string, you can use a command-line tool like base64 or an online encoder. Ensure that your `client_id` and `client_secret` are separated by a colon `:` and then encoded. This encoded string will be used in the Authorization header.

```shell theme={null}
curl --request POST \
  --url https://auth.brale.xyz/oauth2/token \
  --header 'Authorization: Basic ${BASE_64_OF(client_id:client_secret)}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials
```

## Authenticated Requests

Include the bearer token in the Authorization header of your API requests.

```shell theme={null}
curl --request GET \
  --url https://api.brale.xyz/tokens \
  --header 'Authorization: Bearer OiVz67P7emAx0JUJRmYHP4pI-nSlYQn7ivTQE.A-tXeGnuzQBRSjq9QNGQXZ4aRl7Rbm8wY'
```

## Token Expiration

Access tokens are short-lived and expire \~60 minutes after issuance.

When a token expires:

* API calls will return a `401 Unauthorized` error.
* Your application should request a new token using the same client credentials before retrying the request.
* Best practice is to refresh automatically before expiry using `expires_in` and to retry idempotently after refresh.