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

# Client credentials

> Authenticate using the client credentials grant type for server-to-server communication.

Client credentials authentication uses the OAuth 2.0 `client_credentials` grant type for server-to-server communication. Your backend exchanges a client ID and secret for a short-lived access token.

## Get your credentials

Your client ID and secret are provided by Tesouro during onboarding. To request access, have your designated team lead submit an [access request](https://d92rm.share.hsforms.com/2rxMT-N-nQ-atFj2t5ODm2w).

<Danger>
  Store your client secret securely. It is not recoverable after creation — if lost, you must
  submit a new [access request](https://d92rm.share.hsforms.com/2rxMT-N-nQ-atFj2t5ODm2w) to have
  a new one issued.
</Danger>

## Generate an access token

Call the token endpoint with your credentials:

```bash title="Request" lines theme={null}
curl --location 'https://api.sandbox.tesouro.com/openid/connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'client_secret=CLIENT_SECRET'
```

```json title="Response" lines theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

## Use the token

Include the token in the `Authorization` header of subsequent API requests:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

<Info>
  Tokens expire after the duration specified in `expires_in` (in seconds). Your application should
  handle token refresh by requesting a new token before the current one expires.
</Info>

<Info>
  For **production**, use `https://api.tesouro.com` instead of `https://api.sandbox.tesouro.com`
  with your production credentials.
</Info>

## Handle token expiration

An app token expires after the duration specified in `expires_in` (in seconds). If you make a request with an expired token, Tesouro responds with a `400 Bad Request` error:

```json lines theme={null}
{
  "error": {
    "message": "The token has been expired."
  }
}
```

Implement a mechanism on your server to detect this error and automatically request a new token using the same credentials.

## Revoke a token

Tokens expire automatically based on `expires_in`, but you can also revoke one explicitly — for example, when a user logs out of your application.

Call `POST /auth/revoke` with your credentials and the token to revoke:

```bash title="Request" lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/auth/revoke' \
  --header 'Content-Type: application/json' \
  --header 'X-Finops-Version: 2025-06-23' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "token": "eyJ0eXAiOiJKV1QiLCJhb..."
  }'
```

```json title="Response" lines theme={null}
{
  "message": "ok"
}
```