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

# Authentication

The co-mind.ai API supports two authentication methods. Both use the `Authorization: Bearer <token>` header.

<Tabs>
  <Tab title="Personal Access Tokens (Recommended)">
    PATs are long-lived tokens for programmatic API access. They are the recommended method for integrations, scripts, CI/CD pipelines, and any non-interactive usage.

    **Token format:** `cmnd_<tokenId>.<secret>`

    ```bash theme={null}
    # Use a PAT for all API calls
    curl https://your-instance/v1/models \
      -H "Authorization: Bearer cmnd_your-token-here"
    ```

    **Advantages:**

    * Long-lived (up to 365 days)
    * Fine-grained scopes limit access to only what's needed
    * Can be rotated without downtime
    * No refresh flow required

    See [API Tokens](/guides/api-tokens) for full management details.
  </Tab>

  <Tab title="JWT Authentication">
    JWT tokens are short-lived and ideal for interactive sessions (web apps, Postman testing).

    * Access tokens expire in 1 hour
    * Use the refresh token to obtain new access tokens
    * Best suited for browser-based applications

    ```bash theme={null}
    curl https://your-instance/v1/models \
      -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
    ```
  </Tab>
</Tabs>

## JWT Authentication Flow

### Login

`POST /v1/auth/login`

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-instance/v1/auth/login \
    -H "Content-Type: application/json" \
    -d '{
      "email": "user@example.com",
      "password": "your_password"
    }'
  ```

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

  response = requests.post("https://your-instance/v1/auth/login", json={
      "email": "user@example.com",
      "password": "your_password"
  })
  tokens = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://your-instance/v1/auth/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "user@example.com",
      password: "your_password"
    })
  });
  const tokens = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "user_abc123",
    "email": "user@example.com",
    "privileges": ["admin", "auditView"],
    "groupMemberships": ["engineering", "admins"],
    "userVersion": 3
  }
}
```

<Note>
  **LDAP/AD routing:** If the user's email domain matches an IdP configuration, the login request is automatically routed to the configured LDAP/AD directory for authentication. No client-side changes are needed.
</Note>

### SSO Login (Microsoft Entra ID)

`POST /v1/auth/sso`

```bash theme={null}
curl -X POST https://your-instance/v1/auth/sso \
  -H "Content-Type: application/json" \
  -d '{
    "oid": "entra-object-id",
    "tid": "entra-tenant-id",
    "upn": "user@example.com"
  }'
```

### Refresh Token

`POST /v1/auth/refresh`

```bash theme={null}
curl -X POST https://your-instance/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your_refresh_token"}'
```

<Warning>
  The refresh endpoint validates the user's current status — suspended or disabled users are blocked from refreshing tokens.
</Warning>

### Logout

`POST /v1/auth/logout`

```bash theme={null}
curl -X POST https://your-instance/v1/auth/logout \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "your_access_token",
    "refresh_token": "your_refresh_token"
  }'
```

### Get Current User

`GET /v1/auth/me`

```bash theme={null}
curl https://your-instance/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Returns user info including privileges, group memberships, and user version.

## Registration & Password Reset

### Registration Flow

<Steps>
  <Step title="Check Registration">
    ```bash theme={null}
    curl "https://your-instance/v1/auth/check-registration?email=user@example.com"
    ```
  </Step>

  <Step title="Register">
    ```bash theme={null}
    curl -X POST https://your-instance/v1/auth/register \
      -H "Content-Type: application/json" \
      -d '{"email": "user@example.com", "password": "secure_password", "name": "User Name"}'
    ```
  </Step>

  <Step title="Confirm Email">
    ```bash theme={null}
    curl -X POST https://your-instance/v1/auth/confirm \
      -H "Content-Type: application/json" \
      -d '{"email": "user@example.com", "code": "123456"}'
    ```
  </Step>
</Steps>

### Password Reset Flow

<Steps>
  <Step title="Request Reset">
    ```bash theme={null}
    curl -X POST https://your-instance/v1/auth/password-reset-request \
      -H "Content-Type: application/json" \
      -d '{"email": "user@example.com"}'
    ```
  </Step>

  <Step title="Execute Reset">
    ```bash theme={null}
    curl -X POST https://your-instance/v1/auth/password-reset \
      -H "Content-Type: application/json" \
      -d '{"token": "reset_token", "new_password": "new_secure_password"}'
    ```
  </Step>
</Steps>

## Authentication Endpoints Reference

| Endpoint                          | Method | Auth    | Purpose                        |
| --------------------------------- | ------ | ------- | ------------------------------ |
| `/v1/auth/login`                  | POST   | None    | Login and get JWT tokens       |
| `/v1/auth/sso`                    | POST   | None    | SSO login (Microsoft Entra ID) |
| `/v1/auth/refresh`                | POST   | None    | Refresh JWT access token       |
| `/v1/auth/me`                     | GET    | Bearer  | Get current user info          |
| `/v1/auth/logout`                 | POST   | None    | Revoke JWT tokens              |
| `/v1/auth/check-registration`     | GET    | None    | Check if email is registered   |
| `/v1/auth/register`               | POST   | None    | Register new user              |
| `/v1/auth/confirm`                | POST   | None    | Confirm email with auth code   |
| `/v1/auth/change-password`        | POST   | JWT     | Change password                |
| `/v1/auth/password-reset-request` | POST   | None    | Request password reset         |
| `/v1/auth/password-reset`         | POST   | None    | Execute password reset         |
| `/v1/auth/admin/set-password`     | POST   | Service | Admin set user password        |
| `/v1/auth/users/{userId}`         | DELETE | Service | Delete user with cascade       |

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use PATs for integrations">
    PATs are long-lived and scoped — much better than JWTs for automated workflows. Reserve JWTs for interactive sessions.
  </Accordion>

  <Accordion title="Always use HTTPS">
    Never send tokens over HTTP. All production deployments should enforce TLS.
  </Accordion>

  <Accordion title="Store secrets securely">
    Use environment variables or secret managers (AWS Secrets Manager, HashiCorp Vault) — never commit tokens to source control.
  </Accordion>

  <Accordion title="Use minimal scopes">
    Only request the permissions you need. A read-only integration should not have `write` scopes.
  </Accordion>

  <Accordion title="Rotate tokens periodically">
    Use the `POST /v1/api-tokens/{id}/rotate` endpoint for seamless rotation without downtime.
  </Accordion>

  <Accordion title="Revoke unused tokens">
    Delete tokens that are no longer needed using `DELETE /v1/api-tokens/{id}`.
  </Accordion>

  <Accordion title="Never commit tokens to source control">
    Use `.env` files, CI/CD secrets, or secret managers instead.
  </Accordion>
</AccordionGroup>