> ## 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.

# Lender Login

> Authenticate with the ClearGrid API and obtain an access token

Authenticate a lender with the system and obtain an `auth_token` for subsequent API calls. The login endpoint returns both an access token (used for all API requests) and a refresh token (used to obtain a new access token when the current one expires).

## Request

<Note>
  Your lender identifier and credentials are provided by ClearGrid during onboarding. Store the password securely — it should never be exposed in client-side code or version control.
</Note>

### Endpoint

```
POST {{base_url}}/admin/auth/{{lender}}/login
```

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

### Body Parameters

<ParamField body="email" type="string" required>
  The lender email address provided by ClearGrid during onboarding.
</ParamField>

<ParamField body="password" type="string" required>
  The lender-specific password provided by ClearGrid. This should be stored securely and never hardcoded.
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://v3-api.cleargrid.ai/admin/auth/{your_lender_id}/login \
    -H "Content-Type: application/json" \
    -d '{
      "email": "user@example.com",
      "password": "securepassword"
    }'
  ```

  ```javascript JavaScript (fetch) theme={null}
  const response = await fetch(
    'https://v3-api.cleargrid.ai/admin/auth/{your_lender_id}/login',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: 'user@example.com',
        password: 'securepassword'
      })
    }
  );

  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}/login",
      json={
          "email": "user@example.com",
          "password": "securepassword"
      }
  )

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

## Response

<Tabs>
  <Tab title="200 — Success">
    ```json theme={null}
    {
      "lenderPublicId": "<lender_uuid>",
      "token": "<access_token>",
      "refreshToken": "<refresh_token>"
    }
    ```

    | Field            | Type   | Description                                                                                                                                                           |
    | ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `lenderPublicId` | string | The lender's unique public identifier (UUID). Used as a path parameter in subsequent API calls.                                                                       |
    | `token`          | string | The access token. Include this as a Bearer token in the `Authorization` header for all further API requests.                                                          |
    | `refreshToken`   | string | The refresh token. Use this with the [Refresh Token](/api-reference/authentication/refresh-token) endpoint to obtain a new access token when the current one expires. |
  </Tab>

  <Tab title="401 — Unauthorized">
    ```json theme={null}
    {
      "error": "Incorrect username or password."
    }
    ```

    This response indicates that the provided email or password is incorrect. Verify your credentials and try again.
  </Tab>

  <Tab title="500 — Server Error">
    ```json theme={null}
    {
      "error": "Something went wrong. Please try again later."
    }
    ```

    An unexpected server error occurred. If this persists, contact ClearGrid support.
  </Tab>
</Tabs>

## Using the Access Token

Once authenticated, include the access token as a Bearer token in the `Authorization` header of every subsequent API request:

```bash theme={null}
curl -X POST https://v3-api.cleargrid.ai/admin/v3/lenders/{lenderPublicId}/accounts \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

<Warning>
  Access tokens expire after a set period. When a token expires, use the [Refresh Token](/api-reference/authentication/refresh-token) endpoint to obtain a new one without requiring the user to re-enter credentials.
</Warning>

## Security Best Practices

* **Store credentials securely** — Use environment variables or a secrets manager. Never hardcode passwords in source code.
* **Rotate tokens** — Use the refresh token flow to keep sessions alive without storing long-lived credentials.
* **Use HTTPS only** — All API communication must use HTTPS. Plain HTTP requests will be rejected.
* **Limit credential access** — Restrict who on your team has access to lender API credentials.


## OpenAPI

````yaml /api-reference/openapi.json POST /admin/auth/{lender}/login
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}/login:
    post:
      tags:
        - Authentication
      summary: Lender login
      description: >-
        Authenticate a lender and obtain an access token and refresh token for
        subsequent API calls.
      operationId: lenderLogin
      parameters:
        - in: path
          name: lender
          required: true
          schema:
            type: string
          description: >-
            Your lender subdomain identifier, provided by ClearGrid during
            onboarding.
          example: my-lender
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                  description: >-
                    The lender email address provided by ClearGrid during
                    onboarding.
                phone:
                  type: string
                  example: '+971501234567'
                  description: Optional phone number for authentication.
                password:
                  type: string
                  example: password123
                  description: >-
                    The lender-specific password provided by ClearGrid. Store
                    securely and never hardcode.
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: >-
                      Access token. Include as a Bearer token in the
                      Authorization header for all further API requests.
                  refreshToken:
                    type: string
                    description: >-
                      Refresh token. Use with the Refresh Token endpoint to
                      obtain a new access token when the current one expires.
                  lenderPublicId:
                    type: string
                    description: >-
                      The lender's unique public identifier (UUID). Used as a
                      path parameter in subsequent API calls.
              example:
                token: <access_token>
                refreshToken: <refresh_token>
                lenderPublicId: <lender_uuid>
        '401':
          description: Unauthorized — invalid credentials
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: Incorrect username or password.

````