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

# Authentication

> How to authenticate with the Risk Intelligence API using JWT-based credentials.

The Risk Intelligence API uses **JWT-based authentication**. Clients authenticate using a `client_id` and
`client_secret` to obtain an **access token**, which is then used to authorize all subsequent API requests.4

<Note>
  The `client_id` and `client_secret` will be provided by our customer support team upon onboarding.
</Note>

***

### Integration Steps

#### 1. Access Token Creation

Clients initiate authentication by sending a `POST` request to the `/v1/auth` endpoint with their `client_id`
and `client_secret`.

If successful, the response includes:

* `access_token` — a short-lived token used for authenticating API requests
* `refresh_token` — used to renew the access token without re-authenticating

#### 2. Access Token Refresh

When the access token expires, clients can request a new one by sending a `POST` request to `/v1/auth/refresh` with a
valid `refresh_token`.

#### 3. Usage in API Requests

Include the access token in the `Authorization` header of every API request: `Authorization: Bearer <access_token>`

***

### 📈 Rate Limit

To ensure fair usage and system stability, the API enforces rate limits.

* If a client exceeds the rate limit, the API responds with: `429 Too Many Requests`
* A `Retry-After` header will be included in the response, indicating how long the client must wait before retrying the request.

<Note>
  Be sure to implement retry logic and token refresh handling in your integration to avoid disruptions.
</Note>