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

# Authentication

> Issuance and use of the access token.

Authentication takes place in two steps. In the first, the API key is exchanged for an access token. In the second, the token is presented in each request to the protected operations.

## API key

The API key is composed of a public identifier and a secret. The secret is displayed only once, when the key is generated, and cannot be retrieved afterwards. The key identifies the holding account, so that every authenticated operation is restricted to the data of that account.

## Token issuance

The `POST /auth` operation issues the access token. The request uses the HTTP Basic authentication scheme (RFC 7617): the public identifier takes the position of the username, and the secret, that of the password.

```bash theme={null}
curl -X POST https://api.fincle.com.br/auth \
  -u "$FINCLE_API_KEY:$FINCLE_API_SECRET"
```

```json theme={null}
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 60000
}
```

| Field | Description |
| - | - |
| `token` | Access token, in JSON Web Token format (RFC 7519). |
| `tokenType` | Scheme under which the token is presented. The value is `Bearer`. |
| `expiresIn` | Token lifetime, in milliseconds. |

Invalid credentials result in a `401` response.

## Token use

The token is presented in the `Authorization` header, under the Bearer scheme (RFC 6750).

```bash theme={null}
curl https://api.fincle.com.br/balance \
  -H "Authorization: Bearer $FINCLE_TOKEN"
```

A missing, invalid or expired token, or a blocked holding account, results in a `401` response. A resource belonging to another account is treated as nonexistent and results in a `404` response.

## Lifetime and renewal

The token is valid for one minute. There is no renewal operation: once the lifetime has elapsed, a new token must be issued through `POST /auth`. It is recommended that the integration keep the token in memory, track the expiry time from `expiresIn` and request a new token ahead of expiry, rather than waiting for a `401` response.

> [!WARNING]
>
> The API key and the access token must not be embedded in applications running on the end user's device or in source code repositories. Requests must originate exclusively from servers under the integrator's control.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.