auth.md for agents

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

Discovery

Agents can start with the public document:

curl https://api.crownest.dev/auth.md

Unauthenticated API responses also include:

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

service_auth

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

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

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.

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

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

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

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.