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

# Refresh Token

> Refresh an expired MCP Identity Token

# Refresh Token

Refresh an expired MCP Identity Token (MIT) using a refresh token.

## Request

```bash theme={null}
curl -X POST https://api.mcprank.com/v1/identity/refresh \
  -H "X-API-Key: sk_mcp_rank_..." \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "rt_abc123..."}'
```

### Headers

<ParamField header="X-API-Key" type="string" required>
  Your MCP Rank API key
</ParamField>

### Body Parameters

<ParamField body="refresh_token" type="string" required>
  The refresh token from the original token response
</ParamField>

## Response

<ResponseField name="access_token" type="string">
  New MCP Identity Token (JWT)
</ResponseField>

<ResponseField name="refresh_token" type="string">
  New refresh token (old one is invalidated)
</ResponseField>

<ResponseField name="expires_in" type="integer">
  Seconds until the new access token expires (typically 3600)
</ResponseField>

<ResponseField name="token_type" type="string">
  Always `Bearer`
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.mcprank.com/v1/identity/refresh \
    -H "X-API-Key: sk_mcp_rank_..." \
    -H "Content-Type: application/json" \
    -d '{"refresh_token": "rt_abc123..."}'
  ```

  ```python Python theme={null}
  from mcp_rank import MCPRankClient

  client = MCPRankClient(api_key="sk_mcp_rank_...", user_id="user_123")
  await client.initialize()

  # Refresh when needed
  new_tokens = await client.refresh_user_token()
  print(f"New access token: {new_tokens['access_token']}")

  # The client automatically updates its stored tokens
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "rt_xyz789...",
    "expires_in": 3600,
    "token_type": "Bearer"
  }
  ```
</ResponseExample>

## Token Rotation Security

MCP Identity implements refresh token rotation for security:

1. Each refresh token can only be used **once**
2. Using a refresh token returns a **new** refresh token
3. The old refresh token is immediately invalidated
4. If a refresh token is reused (potential attack), all user tokens may be revoked

<Warning>
  Always use the new refresh token from the response. The old refresh token is invalidated after use.
</Warning>

## Error Responses

| Status Code | Error           | Description                                     |
| ----------- | --------------- | ----------------------------------------------- |
| 400         | `invalid_grant` | Invalid, expired, or already-used refresh token |
| 401         | -               | Missing or invalid API key                      |
| 429         | -               | Rate limit exceeded                             |

```json Error Response theme={null}
{
  "detail": "Invalid or expired refresh token"
}
```