# DeliveryKit Agent Registration

DeliveryKit supports WorkOS AuthKit Agent Registration for `service_auth` registration. Anonymous registration is not accepted because DeliveryKit workspaces are owned by verified merchant users.

Status: unavailable until the WorkOS Authentication -> Agents settings and WORKOS_AUTHKIT_DOMAIN are configured

## Endpoints

- Protected resource metadata: https://deliverykit.app/.well-known/oauth-protected-resource/mcp
- Authorization server metadata: https://deliverykit.app/.well-known/oauth-authorization-server
- Registration endpoint: https://deliverykit.app/agent/identity
- Claim restart endpoint: https://deliverykit.app/agent/identity/claim
- Claim-link endpoint for signed-in users: https://deliverykit.app/agent/identity/claim/link
- Claim completion endpoint: https://deliverykit.app/agent/identity/claim/complete
- MCP endpoint after credential exchange: https://deliverykit.app/mcp


## Flow

1. Start with `POST /agent/identity` using `{"type":"service_auth","login_hint":"merchant@example.com"}`.
2. Send the human to the returned WorkOS verification URI so they can sign in or sign up and consent.
3. After the signed-in human reaches DeliveryKit, send them to the attempt URL from `claim.attempt.verification_uri` with its `token` value mapped to DeliveryKit's `claim_attempt_token`, or call `POST /agent/identity/claim/link` with that same WorkOS claim-attempt token, `target` set to `existing` plus an authorized `workspace_id`, or `target` set to `new` plus a desired `workspace_name`, and a stable `idempotency_key`. Do not send a WorkOS `organization_id`; DeliveryKit derives the matching organization from the authorized workspace. Do not use `claim.token` for this step; that token is for starting or completing the WorkOS claim.
4. Show the returned `user_code` to the agent so it can call `POST /agent/identity/claim/complete`.
5. Exchange the returned WorkOS identity assertion at the configured WorkOS AuthKit `/oauth2/token` endpoint. Include `resource=https://deliverykit.app/mcp` so the access token audience is accepted by DeliveryKit MCP.
6. Call `https://deliverykit.app/mcp` with that WorkOS access token. DeliveryKit validates the token issuer, signature, audience, scope, claimed-user delegation, and locally linked WorkOS agent registration before granting MCP access.

WorkOS API-key credentials are not accepted by DeliveryKit MCP unless a future server-side credential validation path is added. Use short-lived WorkOS access tokens.

## Safety

- Do not treat `login_hint` as verified identity.
- Do not request or expose WorkOS admin API keys.
- Do not create a workspace until a signed-in DeliveryKit user links the WorkOS claim attempt.
- Do not send unclaimed, unscoped, wrong-audience, or API-key credentials to the MCP endpoint.
- Retry claim linking with the same `idempotency_key` after uncertain responses.
- If WorkOS Agent Registration is disabled or unavailable, stop and ask the human to enable Authentication -> Agents in the WorkOS Dashboard.