auth.md for agents

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

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

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

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.