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

# Refresh Token

> Exchange a refresh token for a new access token. The old refresh token is invalidated and a new one is returned.

<Note>
  Authenticate with HTTP Basic Auth: `Authorization: Basic base64(client_id:client_secret)`
</Note>

<RequestExample>
  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.commune.email/oauth/token', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      grant_type: 'refresh_token',
      refresh_token: storedRefreshToken,
    }),
  });

  const data = await response.json();
  // IMPORTANT: Save the new refresh_token — the old one is now invalid
  ```

  ```python Python theme={null}
  resp = httpx.post(
      'https://api.commune.email/oauth/token',
      headers={
          'Authorization': f'Basic {credentials}',
          'Content-Type': 'application/json',
      },
      json={
          'grant_type': 'refresh_token',
          'refresh_token': stored_refresh_token,
      },
  )

  data = resp.json()
  # Save data['refresh_token'] — old one is invalid
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.commune.email/oauth/token \
    -H "Authorization: Basic $(echo -n 'comm_client_xxx:comm_secret_xxx' | base64)" \
    -H "Content-Type: application/json" \
    -d '{"grant_type": "refresh_token", "refresh_token": "comm_refresh_xxx..."}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "access_token": "comm_oauth_new...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "comm_refresh_new...",
    "id_token": "eyJhbGciOi...",
    "agent_id": "agt_4f3a9b2c1d7e8a9b",
    "scope": "identity"
  }
  ```
</ResponseExample>

### Body

<ParamField body="grant_type" type="string" required>
  Must be `"refresh_token"`.
</ParamField>

<ParamField body="refresh_token" type="string" required>
  From a previous `verify-code` or `token` response.
</ParamField>

### Response

Same shape as `POST /oauth/verify-code`. Includes a new `access_token`, new `refresh_token`, and updated `id_token`.

<Warning>
  Each refresh token can only be used once. Always save the new `refresh_token` from the response. If you lose it, the agent will need to sign in again.
</Warning>

### Errors

| Code | HTTP | Description |
| - | - | - |
| `invalid_grant` | 401 | Refresh token is invalid, expired, or already used. |
| `unsupported_grant_type` | 400 | `grant_type` is not `"refresh_token"`. |
| `agent_inactive` | 403 | Agent account has been suspended. |


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