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

# Authentication

> Authenticate with API keys using the Authorization Bearer header.

The Broker Panel API uses API keys. Send one API key with every request.

## Send The API Key

Send the key as a Bearer token in the `Authorization` header:

```http theme={null}
Authorization: Bearer [redacted]
```

The API reads only this Bearer token for public API authentication. It does not read an `X-API-Key` header. The `Bearer` scheme must have an uppercase `B` and one space before the key. Header names are not case-sensitive.

## Use The Correct Key Type

| Key type | Format                                           | API mode |
| -------- | ------------------------------------------------ | -------- |
| Live     | `sk_live_` followed by 64 hexadecimal characters | `live`   |
| Sandbox  | `sk_test_` followed by 64 hexadecimal characters | `test`   |

## Key State

Only a key with the `active` state can authenticate.

* An inactive key returns the same authentication error as an invalid key.
* An expired active key returns an expiration error.
* Regeneration replaces the secret. The old secret stops working immediately.
* Deletion removes the key. The deleted secret cannot authenticate.

## Scope Checks

Each endpoint requires one or more scopes. The `admin:full` scope satisfies every scope check. When an endpoint lists multiple scopes, the key needs any one of them.

| Scope              | Access                                                                               |
| ------------------ | ------------------------------------------------------------------------------------ |
| `services:read`    | List services without credentials.                                                   |
| `services:write`   | Create services and check service-write access.                                      |
| `requests:read`    | List service requests.                                                               |
| `requests:write`   | Approve or deny service requests.                                                    |
| `reports:generate` | Generate and email service or invoice reports.                                       |
| `admin:full`       | Use every endpoint, including credential-bearing and destructive service operations. |

A missing scope returns HTTP `403` with the `insufficient_permissions` error code.

## Verify API Access

Use [Verify API Access](/api/verify-api-access) to choose the correct check and follow the recommended verification sequence.

* `GET /v1/auth-check` verifies general authentication without requiring a feature scope.
* `POST /v1/auth-check` verifies `services:write` or `admin:full` access without creating a service.

## Authentication Errors

| HTTP status | Error code                 | Cause                                                                       | Action                                                                 |
| ----------- | -------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `401`       | `authentication_failed`    | The Bearer token is missing.                                                | Add the `Authorization` header.                                        |
| `401`       | `authentication_failed`    | The key is invalid or is not active.                                        | Check the key. Activate it or create a new key.                        |
| `401`       | `authentication_failed`    | The key has expired.                                                        | Create or use an unexpired key.                                        |
| `403`       | `insufficient_permissions` | The request IP address is not in the broker whitelist for a restricted key. | Add the exact outbound IP address or disable the key's IP restriction. |
| `403`       | `insufficient_permissions` | The key does not have a required scope.                                     | Add the required access or use a different key.                        |
| `429`       | `rate_limit_exceeded`      | The key has reached its rate limit.                                         | Wait for the number of seconds in the `Retry-After` header.            |
| `500`       | `server_error`             | Authentication or the authentication check could not complete.              | Try again. Contact support if the error continues.                     |

Read [IP Firewall](/api/firewall) for IP restriction rules.