> ## Documentation Index
> Fetch the complete documentation index at: https://alliancebioversityciat-alliance-risk-analysis-tool.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Refresh Token

> Exchanges a refresh token for new access tokens

Exchanges a Cognito refresh token for a new access token and ID token. Use this endpoint to maintain an authenticated session without requiring the user to log in again.

## Authentication

This is a public endpoint that does not require authentication. However, you must provide a valid refresh token obtained from a previous login.

## Rate Limiting

This endpoint is rate-limited to **5 requests per minute** per IP address.

## Request Body

**refreshToken** `string` *required*

Cognito refresh token obtained from a previous login response

This is the long-lived token returned by `/api/auth/login`.

**Example:** `eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ...`

## Request Example

```bash theme={null}
curl -X POST https://api.example.com/api/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ..."
  }'
```

## Response

### Success Response (200 OK)

**accessToken** `string`

New Cognito JWT access token

Use this token in the `Authorization: Bearer <token>` header for authenticated requests.

**refreshToken** `string`

The same refresh token that was provided in the request

Cognito does not issue a new refresh token on refresh, so the original token is returned.

**expiresIn** `number`

Token expiration time in seconds

Typically 3600 (1 hour).

**requiresPasswordChange** `boolean`

Always `false` for refresh token responses

```json theme={null}
{
  "accessToken": "eyJraWQiOiJxYz...",
  "refreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ...",
  "expiresIn": 3600,
  "requiresPasswordChange": false
}
```

## Error Responses

**401 Unauthorized**

**Invalid or expired refresh token**

The refresh token is malformed, expired, or has been revoked.

```json theme={null}
{
  "statusCode": 401,
  "message": "Invalid or expired refresh token",
  "error": "Unauthorized"
}
```

**429 Too Many Requests**

**Rate limit exceeded** — More than 5 requests in 1 minute

```json theme={null}
{
  "statusCode": 429,
  "message": "Too many requests",
  "error": "Too Many Requests"
}
```

## Notes

* Refresh tokens are long-lived and remain valid until explicitly revoked
* Cognito does not rotate refresh tokens automatically—the same refresh token can be used multiple times
* Access tokens expire after 1 hour, so refresh them before they expire to maintain a seamless user experience
* If the refresh token is expired or invalid, the user must log in again using `/api/auth/login`


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