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

# Authentication

The Envoy AI API supports two authentication methods. Choose the one that fits your use case.

## Bearer token

Bearer tokens are short-lived JWTs for interactive sessions. Use them when building user-facing applications or testing from the dashboard.

Obtain a token by calling the login endpoint:

```bash
curl -X POST https://tryenvoy.ai/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'
```

The response includes an `access_token`:

```json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer"
}
```

Include it in subsequent requests using the `Authorization` header:

```bash
curl https://tryenvoy.ai/api/v1/loads \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
```

## API key

API keys are long-lived credentials for programmatic access. Use them for TMS integrations, automated pipelines, and server-to-server communication. Each key is scoped to your organization.

Create an API key through the dashboard or via the API:

```bash
curl -X POST https://tryenvoy.ai/api/v1/api-keys \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "TMS Integration"}'
```

The key value is returned **once** in the response. Store it securely -- it cannot be retrieved again.

Include it in requests using the `X-API-Key` header:

```bash
curl https://tryenvoy.ai/api/v1/loads \
  -H "X-API-Key: envai_live_abc123..."
```

## When to use each method

| Method           | Best for                                       | Lifetime                   | Header                          |
| ---------------- | ---------------------------------------------- | -------------------------- | ------------------------------- |
| **Bearer token** | Dashboard, interactive sessions, testing       | Short-lived (hours)        | `Authorization: Bearer <token>` |
| **API key**      | TMS integrations, batch operations, automation | Long-lived (until revoked) | `X-API-Key: <key>`              |

## Security best practices

* **Rotate API keys regularly.** Use the regenerate endpoint to issue a new key without downtime.
* **Never expose keys in client-side code.** API keys belong on your server, not in browser JavaScript or mobile apps.
* **Set expiration dates** on keys used for time-limited integrations.
* **Use separate keys for separate integrations.** This limits blast radius if a key is compromised.
* **Deactivate unused keys immediately** via `DELETE /api-keys/{id}`.