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

# Authentication and credits

> Authenticate API calls, estimate access, and handle account responses safely.

## API key authentication

Send your key in the `X-API-Key` header on every public request.

```http theme={null}
X-API-Key: astrom8_live_...
```

Treat keys as secrets. Keep them in server-side environment variables, use separate keys per environment, and rotate a key immediately if it may have been exposed.

## Customer session authentication

Customer delivery and report-management routes use an `astrom8_sess_*` bearer token returned by the customer authentication flow, not an API key. The reference marks those operations with `SessionBearerAuth`; do not send a customer session token to API-key endpoints.

## Tiers and credits

The reference declares requirements per endpoint. Some calculations are available synchronously; premium interpretation and PDF workflows may require a higher tier or debit credits after the request is accepted.

Use `POST /api/v3/estimates` to inspect eligibility and the estimated debit before submitting a billable capability. The actual endpoint remains authoritative: it checks tier, balance, idempotency, and debit atomically.

## Common responses

| Status | Meaning                                               | What to do                                           |
| ------ | ----------------------------------------------------- | ---------------------------------------------------- |
| `400`  | Input failed validation.                              | Correct the request from the field-level error.      |
| `401`  | API key is missing, invalid, or disabled.             | Check the key and environment.                       |
| `402`  | The key has insufficient credits.                     | Add credits or use an authorized internal key.       |
| `403`  | The operation is not allowed for this tier.           | Upgrade the tier or choose another capability.       |
| `409`  | An idempotent request conflicts with a prior payload. | Reuse the original payload or a new idempotency key. |
| `429`  | Rate limit reached.                                   | Respect the retry information and back off.          |
| `5xx`  | The service could not complete the request.           | Retry only when the operation is safe to retry.      |

See [rate limits and errors](/guides/rate-limits-and-errors) for retry and idempotency guidance.