# Authenticating with Gecko

How an agent authenticates across Gecko's surfaces. Spec vocabulary per
WorkOS auth.md; every URI below is live and probeable.

## Discover

- Protected-resource metadata (RFC 9728, this site): https://geckovision.tech/.well-known/oauth-protected-resource
- Protected-resource metadata (the hosted MCP): https://mcp.geckovision.tech/.well-known/oauth-protected-resource
- The MCP host's PRM lists agent_auth (identity_endpoint, claim_endpoint) and
  scopes_supported: the REAL per-surface grant scopes (surface:<name>).
- There is NO oauth-authorization-server metadata anywhere: no OAuth 2.0
  authorization server exists, and we do not fabricate one. identity_assertion
  and service_auth (including id-jag assertions) are therefore NOT supported;
  identity_types_supported is ["anonymous"].

## Pick a method

- This site's API (https://geckovision.tech/api/v1/*): anonymous. No credential, no scopes.
- The hosted MCP (https://mcp.geckovision.tech/orquestra/mcp): open surfaces are anonymous; GATED surfaces
  need a Gecko key (a bearer credential, not an OAuth access_token).

## Register

Registration is starting an email login: no account form, no OAuth client:

    POST https://mcp.geckovision.tech/auth/login/start
    {"email": "you@example.com"}

This is the identity_endpoint the PRM's agent_auth block advertises. A
verification code is emailed. (A fully headless agent needs inbox access to
finish this step; that is a real limitation, stated here rather than hidden.)

## Claim

Exchange the emailed code for your key at the claim_endpoint:

    POST https://mcp.geckovision.tech/auth/login/verify
    {"email": "you@example.com", "code": "<emailed code>"}

The response carries your Gecko key. Store it like any secret.

## Exchange

There is no token exchange. The key IS the credential: no refresh tokens, no
id-jag assertion exchange, no downstream token minting. Scopes are fixed at
grant time, per surface, deny-by-default.

## Use the access_token

Send the key as a bearer token on every request to a gated surface:

    Authorization: Bearer <your key>

A key opens exactly the surfaces its account was granted (scope
surface:<name>), never the host.

## Errors

Every denial is structured JSON, never HTML. A gated surface answers 401 with
a WWW-Authenticate: Bearer challenge that carries resource_metadata (the PRM
URL) and error_description, and a body naming this mint path. This site's API
errors are {"error": {"code", "message", "hint"}} with RateLimit headers and
Retry-After on 429.

## Revocation

Keys can be disabled server-side (deny-by-default takes effect on the next
request). To revoke a key or a surface grant, email contact@geckovision.tech
from the enrolled address. Self-serve revocation is not built yet - stated
honestly rather than implied.

## Sandbox

The $0 recorded mode needs no credential at all: every surface can synthesize
schema-true responses offline, and the purchase path can be rehearsed against
a local surfpool fork you run yourself. Docs: https://docs.geckovision.tech