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

# Refresh Token

> Refresh an expired access token using the refresh token

Use the refresh token obtained from the [Lender Login](/api-reference/authentication/lender-login) endpoint to obtain a new access token without re-authenticating with email and password. This enables seamless token rotation for long-running integrations.

## Request

### Endpoint

```
POST {{base_url}}/admin/auth/{{lender}}/refresh-token
```

| Environment    | Base URL                             |
| -------------- | ------------------------------------ |
| **Production** | `https://v3-api.cleargrid.ai/`       |
| **Staging**    | `https://stage-v3-api.cleargrid.ai/` |

### Body Parameters

<ParamField body="refreshToken" type="string" required>
  The refresh token obtained from the [Lender Login](/api-reference/authentication/lender-login) response.
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://v3-api.cleargrid.ai/admin/auth/{your_lender_id}/refresh-token \
    -H "Content-Type: application/json" \
    -d '{
      "refreshToken": "<refresh_token>"
    }'
  ```

  ```javascript JavaScript (fetch) theme={null}
  const response = await fetch(
    'https://v3-api.cleargrid.ai/admin/auth/{your_lender_id}/refresh-token',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        refreshToken: '<refresh_token>'
      })
    }
  );

  const data = await response.json();
  console.log(data.token);
  ```

  ```python Python (requests) theme={null}
  import requests

  response = requests.post(
      "https://v3-api.cleargrid.ai/admin/auth/{your_lender_id}/refresh-token",
      json={
          "refreshToken": "<refresh_token>"
      }
  )

  data = response.json()
  print(data["token"])
  ```
</CodeGroup>

## Response

<Tabs>
  <Tab title="200 — Success">
    ```json theme={null}
    {
      "token": "<access_token>"
    }
    ```

    | Field   | Type   | Description                                                                                                     |
    | ------- | ------ | --------------------------------------------------------------------------------------------------------------- |
    | `token` | string | The new access token. Use this as a Bearer token in the `Authorization` header for all subsequent API requests. |
  </Tab>

  <Tab title="401 — Invalid Token">
    ```json theme={null}
    {
      "code": 401,
      "message": "Token Type is not refresh",
      "body": null
    }
    ```

    This error occurs when you pass an access token instead of a refresh token. Make sure to use the `refreshToken` value from the original login response.
  </Tab>

  <Tab title="400 — Bad Request">
    ```json theme={null}
    {
      "type": "about:blank",
      "title": "Bad Request",
      "status": 400,
      "detail": "Failed to read request",
      "instance": "/api/v1/auth/{lender}/refresh-token",
      "properties": null
    }
    ```

    The request body is malformed or missing required fields. Ensure the JSON body includes a valid `refreshToken` field.
  </Tab>
</Tabs>

## Token Refresh Flow

```mermaid theme={null}
sequenceDiagram
    participant App as Your Application
    participant API as ClearGrid API

    App->>API: API call with access token
    API-->>App: 401 - Token expired

    App->>API: POST /admin/auth/{lender}/refresh-token
    Note right of App: Send refreshToken in body
    API-->>App: 200 - New access token

    App->>API: Retry original API call with new token
    API-->>App: 200 - Success
```

<Tip>
  Implement automatic token refresh in your integration. When any API call returns a `401` response, call the refresh token endpoint and retry the failed request with the new access token.
</Tip>


## OpenAPI

````yaml /api-reference/openapi.json POST /admin/auth/{lender}/refresh-token
openapi: 3.1.0
info:
  title: Command API
  description: >-
    RESTful API for lenders to manage accounts and borrower data in the Command
    platform.
  version: 3.0.0
servers:
  - url: https://v3-api.cleargrid.ai
    description: Production
  - url: https://stage-v3-api.cleargrid.ai
    description: Staging
security: []
paths:
  /admin/auth/{lender}/refresh-token:
    post:
      tags:
        - Authentication
      summary: Refresh access token
      description: >-
        Exchange a refresh token for a new access token without requiring the
        user to re-authenticate.
      operationId: refreshToken
      parameters:
        - in: path
          name: lender
          required: true
          schema:
            type: string
          description: Your lender subdomain identifier.
          example: my-lender
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - refreshToken
              properties:
                refreshToken:
                  type: string
                  example: eyJhbGciOiJIUzUxMiJ9...
                  description: The refresh token obtained from the Lender Login response.
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: >-
                      New access token. Use as a Bearer token in the
                      Authorization header.
              example:
                token: <new_access_token>
        '400':
          description: Bad request — malformed body or missing refreshToken
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
                  instance:
                    type: string
              example:
                type: about:blank
                title: Bad Request
                status: 400
                detail: Failed to read request
                instance: /api/v1/auth/{lender}/refresh-token
        '401':
          description: Unauthorized — token type mismatch or invalid token
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
                  body:
                    type: string
                    nullable: true
              example:
                code: 401
                message: Token Type is not refresh
                body: null

````