> For the complete documentation index, see [llms.txt](https://shinkalabs.gitbook.io/hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shinkalabs.gitbook.io/hub/andromeda/getting-started/auth.md).

# Authentication

Andromeda authenticates API requests with a single header.

```
X-Api-Key: <your key>
```

## Public vs authenticated routes

| Route                                    | Auth    |
| ---------------------------------------- | ------- |
| `GET /capabilities`                      | none    |
| `GET /openapi.json`                      | none    |
| `GET /v1/pricing`                        | none    |
| `POST /v1/pricing/estimate`              | API key |
| everything else under `/v1/*` and `/mcp` | API key |
| `GET /health`, `GET /health/ready`       | none    |

## What the key controls

* **Scope.** The key must hold the scope the route requires (`read`, `write`, or `admin`). See [Get an API key](/hub/andromeda/getting-started/api-key.md).
* **Source IP.** If the key has an IP allowlist, the request must come from inside it.
* **Quota.** Each call charges the key's quota according to the operation's cost. See [Quotas & rate limits](/hub/andromeda/pricing/quotas.md).
* **Rate limit.** Calls are throttled per key in two buckets: a generous `read` bucket and a smaller `tx` bucket for signing, prepares, submits and other engine-touching work.
* **Audit and webhooks.** Actions taken with the key are recorded in that tenant's [audit log](/hub/andromeda/guides/audit-log.md) and can fan out as [webhooks](/hub/andromeda/guides/webhooks.md).

## Error responses

| Situation                            | HTTP status                |
| ------------------------------------ | -------------------------- |
| Missing or unknown key               | `401`                      |
| Key lacks the required scope         | `403`                      |
| Source IP not in the key's allowlist | `403`                      |
| Quota exhausted                      | `402`                      |
| Rate limit exceeded                  | `429` (with `Retry-After`) |
| Request body too large               | `413`                      |

See [Error codes](/hub/andromeda/api-reference/errors.md) for the full list and response shape.

## CORS

The API allows browser requests only from origins the deployment has configured, and it does not allow credentials. The API key is meant for server-to-server use; do not rely on browser CORS to call authenticated endpoints directly from a web page.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://shinkalabs.gitbook.io/hub/andromeda/getting-started/auth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.