Authentication — Markdown source

> **AI Agents**: Index `/api/llms.txt` | Full EN `/api/llms-full-en.txt` | Full ZH `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# Authentication

SupaNexus uses **Bearer API key** authentication, compatible with OpenAI client libraries.

## Header format

```http
Authorization: Bearer <API_KEY>
```

Include your API key secret in the `Authorization` header. SupaNexus validates the key on every request.

## Creating an API key

1. Sign in to the [Developer Console](https://console.supanexus.ai).
2. Open your organization → project → **API Keys**.
3. Create a key and copy the secret immediately (shown once).

Each key is scoped to a **project** and **organization**. Usage is metered against that project.

## Expiration

If the key has an expiration timestamp and is past due, requests return **401**:

```json
{
  "error": {
    "code": 401,
    "message": "Invalid credentials. Provide a valid API key in the Authorization header."
  }
}
```

## Missing or invalid key

| Condition | HTTP | Body |
|-----------|------|------|
| No `Authorization` header | 401 | `{"error":{"code":401,"message":"..."}}` |
| Wrong or revoked key | 401 | Same |
| Service temporarily unavailable | 503 | `{"error":{"code":503,"message":"..."}}` |

## Suspended account check

After the API key is validated, SupaNexus also checks the **organization owner’s** platform account status:

| Status | Console sign-in | API `/v1/*` |
|--------|-----------------|-------------|
| Active | Allowed | Allowed |
| Suspended | Denied | **403** (see below) |

Suspension is applied by a platform administrator. After unsuspension, console and API access resume. **API keys are not auto-revoked**, but the API rejects every request while the account is suspended.

```json
{
  "error": {
    "code": 403,
    "message": "Your account has been suspended. Contact support for assistance."
  }
}
```

Do not retry this error; contact SupaNexus support or your administrator.

## What authentication does not cover

- **IP rate limiting** on `/v1/*` also returns OpenRouter-style 429 — see [Rate Limits & Quotas](./rate-limits-and-quotas.md).
- **Usage quota and account balance checks** may run after authentication on `POST /v1/chat/completions` and `POST /v1/messages`, depending on your deployment.

## Security recommendations

- Store keys in environment variables or a secrets manager, never in source control.
- Rotate keys periodically and revoke unused keys in the console.
- Use separate keys per environment (dev/staging/production).