Authentication - Mireye Earth

Every data request to Mireye Earth is authenticated with a bearer token:

Authorization: Bearer <token>

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 (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:

export MIREYE_API_TOKEN="<paste from dashboard>"

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.

The mireye-mcp stdio adapter authenticates once with a browser hand-off and stores the resulting API token locally:

mireye-mcp login

This drives POST /v1/mcp/device/start → browser approval at 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: {"detail": {"error", "message"}}.

`error`	Status	Meaning
`auth_missing`	401	No `Authorization` header on a protected route.
`auth_malformed`	401	Header present but not `Bearer <token>`.
`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.

​Public vs. protected endpoints

​Getting a token

​1. API token from the dashboard (services, scripts, CI)

​2. Device-flow login (local MCP stdio adapter)

​3. OAuth 2.1 + PKCE (hosted MCP endpoint)

​Auth error codes

​Rate limits and quotas