> ## Documentation Index > Fetch the complete documentation index at: https://docs.mireye.ai/llms.txt > Use this file to discover all available pages before exploring further. # Authentication > Bearer tokens for /v1/ask, /v1/fetch, and the hosted MCP endpoint. Every data request to Mireye Earth is authenticated with a bearer token: ```text theme={null} Authorization: Bearer ``` There are no API-key query parameters and no custom headers — one `Authorization` header covers the HTTP API and the local MCP adapter. The hosted MCP endpoint (`/mcp`) authenticates with OAuth 2.1, which MCP clients negotiate automatically. ## Public vs. protected endpoints No token required: * `GET /healthz`, `GET /readyz` — health probes. * `GET /v1/meta/fields` — the field catalog. * `GET /v1/docs`, `GET /v1/openapi.json` — Swagger UI and OpenAPI spec. Token required: * `POST /v1/ask`, `POST /v1/fetch` — all data requests. * `/mcp` — the hosted MCP endpoint (OAuth 2.1 bearer). * Account and token-management routes under `/v1/users/me/*`. ## Getting a token There are three paths, depending on what you're building: ### 1. API token from the dashboard (services, scripts, CI) Sign in at [www.mireye.com](https://www.mireye.com) (Google or email/password with a verified address) and create an API token in account settings. Tokens are JWTs with a 90-day default lifetime; the plaintext is shown at creation and can be re-revealed later from the dashboard as long as the token is still active and `recoverable` (a signing-secret rotation can leave active tokens unrecoverable). Use it directly: ```bash theme={null} export MIREYE_API_TOKEN="" curl -s https://api.mireye.com/v1/fetch \ -H "Authorization: Bearer $MIREYE_API_TOKEN" \ -H 'content-type: application/json' \ -d '{"lat": 40.7128, "lng": -74.0060, "fields": ["elevation"]}' ``` Manage tokens over the API itself (these routes require a Firebase web session, i.e. browser sign-in — API-token callers get `403 auth_method_not_allowed`): | Route | Purpose | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `GET /v1/users/me/tokens` | List tokens with `created_at`, `last_used_at`, and a `recoverable` flag. | | `POST /v1/users/me/tokens` | Create a token; plaintext returned once in the response. | | `POST /v1/users/me/tokens/{id}/reveal` | Re-reveal an active token (recomputed + hash-verified; never stored in plaintext). Rate-limited per user — honor `Retry-After` on 429. | | `DELETE /v1/users/me/tokens/{id}` | Revoke. | ### 2. Device-flow login (local MCP stdio adapter) The [`mireye-mcp`](/mcp/installation) stdio adapter authenticates once with a browser hand-off and stores the resulting API token locally: ```bash theme={null} mireye-mcp login ``` This drives `POST /v1/mcp/device/start` → browser approval at [www.mireye.com](http://www.mireye.com) → `POST /v1/mcp/device/poll`, and saves the token to `~/.config/mireye-mcp/credentials.json`, bound to the `MIREYE_BASE_URL` it was minted for. Alternatively, set `MIREYE_BEARER_TOKEN` in the adapter's environment with a dashboard token. ### 3. OAuth 2.1 + PKCE (hosted MCP endpoint) MCP clients that connect to `https://api.mireye.com/mcp` (e.g. `claude mcp add --transport http …`) discover and complete OAuth on their own. The API publishes authorization-server metadata at `/.well-known/oauth-authorization-server`, with dynamic client registration at `/register`, authorization at `/authorize`, token exchange at `/token`, and revocation at `/revoke`. Access tokens minted for `/mcp` are scoped to MCP tool calls — they are **not** accepted as general `/v1/*` API tokens. Use a dashboard API token for direct HTTP calls. ## Auth error codes Auth failures use the same structured shape as every other [error](/api-reference/errors): `{"detail": {"error", "message"}}`. | `error` | Status | Meaning | | ----------------------------- | ------ | -------------------------------------------------------------------------------------------- | | `auth_missing` | 401 | No `Authorization` header on a protected route. | | `auth_malformed` | 401 | Header present but not `Bearer `. | | `auth_invalid` | 401 | Token is unknown, revoked, or fails verification. | | `auth_expired` | 401 | Firebase ID token has expired — refresh and retry. | | `auth_revoked` | 401 | Firebase ID token was revoked. | | `provider_not_allowed` | 403 | Sign-in provider other than Google or email/password. | | `email_unverified` | 403 | Verify the account email before using Mireye. | | `user_disabled` | 403 | The Firebase user is disabled. | | `auth_method_not_allowed` | 403 | Route requires a browser (Firebase) session, e.g. token management called with an API token. | | `rate_limited` | 429 | Per-user limit hit (e.g. token reveals). Honor `Retry-After`. | | `account_store_misconfigured` | 500 | Server-side account-store misconfiguration — not caller-recoverable; report it. | Unauthenticated requests to the hosted `/mcp` endpoint return `401` with a `WWW-Authenticate` header pointing at the OAuth metadata, which is how MCP clients know to start the OAuth flow. ## Rate limits and quotas V1 has no metered request quotas — auth is account-based and the deploy is sized for the early-adopter wave. Specific abuse-prevention limits exist on unauthenticated device-flow starts and on token reveals. If you have a high-volume use case, email [ansh@mireye.earth](mailto:ansh@mireye.earth).