# auth.md for agents (/docs/agents/auth-md)



CrowNest supports auth.md so coding agents can discover the API and request
registration. The agent guides you through WorkOS/AuthKit signup or sign-in
and receives a scoped, short-lived agent token without seeing a raw developer
API key.

## Discovery [#discovery]

Agents can start with the public document:

```bash title="Terminal"
curl https://api.crownest.dev/auth.md
```

Unauthenticated API responses also include:

```http
WWW-Authenticate: Bearer resource_metadata="https://api.crownest.dev/.well-known/oauth-protected-resource"
```

The protected-resource metadata links to the CrowNest authorization server
metadata, token endpoint, revocation endpoint, supported scopes, and
currently enabled registration types.

## Registration flows [#registration-flows]

CrowNest supports three registration types in the protocol. Use only the
`registration_types_supported` values advertised by the environment you are
calling; public site discovery currently starts agents with `service_auth`.

### service\_auth [#service_auth]

Use `service_auth` when the agent has an email hint and needs user approval
before receiving access.

```bash title="Terminal"
curl https://api.crownest.dev/agent/identity \
  -H "content-type: application/json" \
  -d '{"type":"service_auth","login_hint":"user@example.com","requested_scopes":["sandbox:create","sandbox:read"]}'
```

CrowNest returns a claim token, a six-digit user code, and the human
verification URL. The user signs in or signs up through WorkOS/AuthKit,
enters the code, selects or confirms the project, and approves or denies
the requested scopes. The agent polls `/oauth2/token` with the claim token
until approval, denial, expiration, or `slow_down`.

### anonymous [#anonymous]

Use `anonymous` for a pre-claim compatibility loop. The agent receives a
CrowNest identity assertion and can exchange it for a pre-claim token with
only `agent:bootstrap`.

```bash title="Terminal"
curl https://api.crownest.dev/agent/identity \
  -H "content-type: application/json" \
  -d '{"type":"anonymous"}'
```

Pre-claim tokens can call `/agent/bootstrap` for public capabilities,
templates, pricing, docs links, and auth.md compatibility metadata. They
cannot create sandboxes or read tenant resources. The agent starts claim
with `/agent/identity/claim`, then the human approval path upgrades the
registration to tenant-scoped developer scopes.

### identity\_assertion [#identity_assertion]

`identity_assertion` is the provider-trust path. CrowNest stores trusted
providers, JWKS metadata, provider bindings, and replay records in Convex.
Production metadata advertises provider identity only after a trusted
provider is enabled and tested. Unbound provider subjects are routed through
WorkOS/AuthKit first-link approval before they can mint tenant-scoped
tokens.

## Token semantics [#token-semantics]

Agent access tokens:

* use the `cn_agent_` prefix;
* are opaque bearer secrets, not JWT access tokens;
* are stored only as hashes with an indexed lookup fragment;
* default to one-hour lifetime;
* are separate from developer API keys in storage, audit, dashboard, and
  revoke semantics.

CrowNest identity assertions are signed JWTs used only for token exchange.
CrowNest assertions can be re-exchanged until expiration or registration
cutoff. Provider ID-JAG and Security Event Tokens are replay-guarded.

## Dashboard management [#dashboard-management]

Owners and admins can open **Agent Access** in the dashboard to inspect
agent registrations separately from API keys. Revoking a registration
revokes active descendant tokens and prevents future assertion exchange.
Revoking through `/oauth2/revoke` only revokes the single presented access
token.

## Operations [#operations]

Before enabling a flow in production, verify:

* `CROWNEST_AGENT_AUTH_SIGNING_SECRET` and `CROWNEST_AGENT_AUTH_KEY_ID` are
  configured as Worker secrets or safe placeholders;
* `CROWNEST_WORKOS_SIGNUP_POSTURE` matches the actual WorkOS environment;
* the `AGENT_AUTH_RATE_LIMITER` Durable Object binding is deployed;
* production metadata advertises only enabled flows;
* provider trust stays disabled until issuer, JWKS, audiences, replay
  guards, SET handling, and revoke runbooks are proven.