> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://one.miles-api.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://one.miles-api.com/_mcp/server.

# Authentication

# Authentication

The Miles USP API uses **dual-JWT Bearer authentication** on a single `Authorization` header. Partner and webhook routes may use additional header tokens documented per endpoint.

## Bearer JWT (primary)

Send every authenticated request with:

```http
Authorization: Bearer <token>
```

The backend resolves the token in order:

1. **SSO JWT** — signed with `SSO_SECRET_KEY`, keyed on `(userId, phone)`. This is the path used by MilesOne mobile and web clients after SSO login.
2. **SimpleJWT admin token** — signed with `JWT_SIGNING_KEY`, keyed on `(user_id, phone)`. Used as a fallback when the SSO decode fails (wrong signature / not an SSO token).

If neither path succeeds, the API returns **401 Unauthorized** with `WWW-Authenticate: Bearer`.

### Optional (soft) auth

Some routes accept a missing or invalid token and return public data (`get_optional_user`). Check the endpoint description in the API Reference for whether auth is required.

## Admin phone OTP login

For admin and internal tooling, obtain a SimpleJWT admin token via:

| Step | Endpoint                        | Purpose                             |
| ---- | ------------------------------- | ----------------------------------- |
| 1    | `POST /v7/login-with-phone-otp` | Send OTP to the admin phone via SSO |
| 2    | `POST /v7/verify-otp`           | Verify OTP; returns admin JWT       |

Use the returned token as the Bearer value in subsequent requests.

## Additional header tokens

Some integration endpoints use dedicated headers instead of (or in addition to) Bearer JWT:

| Header                           | Used for                            |
| -------------------------------- | ----------------------------------- |
| `X-LMS-OPEN-API-KEY`             | LMS partner / open API routes       |
| `X-Enrollment-Form-Vendor-Token` | Enrollment form vendor integrations |
| `X-Vendor-Token`                 | Selected vendor callbacks           |

Configure these in the API Explorer auth dropdown when trying those endpoints.

## API Explorer tips

1. Select **Production**, **UAT**, or **Local** from the server dropdown.
2. Paste your JWT under **BearerAuth** — credentials persist for your session (client-side cookies only).
3. For partner routes, switch to **ApiKeyAuth** or **VendorTokenAuth** in the auth scheme selector.

## Security notes

* Never commit tokens or `.env` files to git.
* Rotate keys exposed in logs, chat, or CI artifacts promptly.
* Lock down `ALLOWED_HOSTS` and CORS per environment in production.