# Signing in to Doing Work as an agent Doing Work is software for trade shops. An agent works for one person, a shop owner or worker, and can only do what that person can do. There are three ways in. All end with a bearer token you send as `Authorization: Bearer `. ## 1. OAuth with PKCE (for MCP clients) 1. Call the MCP endpoint, https://doingwork.work/mcp, without a token. You get 401 with a `WWW-Authenticate` header that points at https://doingwork.work/.well-known/oauth-protected-resource/mcp. 2. Read https://doingwork.work/.well-known/oauth-authorization-server for the endpoints. 3. Register your client at https://doingwork.work/v1/oauth/register (RFC 7591). Public clients only: no secret. Redirects must be https, or http on loopback. 4. Send the person to https://pages.doingwork.work/p/oauth/authorize with a PKCE S256 challenge and `resource=https://doingwork.work/mcp`. Omitted scope means full `agent`. On an OAuth person grant (no shop_id) that can create a shop. A key from agents.register is bound to the shop the owner picks and cannot create another shop. Add `read_only` to look without changes. `read_only` cannot create a shop. Add `no_money` to block charges, refunds, and sending a payment request. They sign in with an emailed link and approve your client. 5. Trade the code and verifier at https://doingwork.work/v1/oauth/token. You get a short lived access token and a refresh token. Refresh tokens work once; reusing one ends the whole chain. You must store the refresh token yourself. Doing Work does not keep a copy you can fetch later, and a successful token response is not proof you saved it. Call me.get before you say you are connected. Use this path when you can open a browser and store a refresh token. Do not also start a claim. A token bound to the MCP endpoint works only there, not on the REST API. ## 2. A named agent key (for REST, MCP and A2A) The shop owner makes a key for your agent with their own sign in (POST https://doingwork.work/v1/keys, owner only, not callable by an agent). The key starts with `dwk_`, is shown once, and works in that one shop only. A key can be narrowed with scopes: `read_only`, `no_money`. `read_only` makes no changes. `no_money` cannot charge, refund, send a payment request, or change payments. A key never does more than the owner can. The owner can revoke it at any time, and it stops at once. ## 3. Register yourself and ask the owner to claim you (agent_auth) Use this when you know the owner's email and you cannot store an OAuth refresh token. Do not also start OAuth. 1. POST https://doingwork.work/v1/agent/identity with `{"type":"service_auth","login_hint":""}`. Optional `client_name` and `scope` (`read_only`, `no_money`). Omitted scope means full `agent`. On an OAuth person grant (no shop_id) that can create a shop. A key from agents.register is bound to the shop the owner picks and cannot create another shop. `read_only` cannot. One call returns `claim_token`, `claim_attempt_token`, `user_code`, `claim_page`, and `verification_uri`. 2. If `complete` is true and `verification_uri.length` equals `verification_uri_length`, give the person `verification_uri`. If the URI was cut, build `claim_page` plus `?claim_attempt_token=` plus `claim_attempt_token` only when both pieces are present and that built link's length equals `verification_uri_length`. Do not invent the host or the path. Do not open `claim_url` by itself. If `complete` is missing and `claim_token` is present but `claim_attempt_token` is not, call POST https://doingwork.work/v1/agent/identity/claim once. If `claim_token` is missing, stop. Do not register again in a loop. The code lasts 10 minutes. Never put `user_code` in a link. 3. Use anonymous, then the claim endpoint, only when you do not yet have the email. 4. Poll https://doingwork.work/v1/oauth/token with `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=...` every `interval` seconds, and only while the error is `authorization_pending`. On `slow_down`, wait the longer interval and poll once more. Stop on `access_denied`, `expired_token`, or `invalid_grant`. Those end this claim. Also stop when `expires_in` has passed. Do not poll until `shown_once`. That field is only on success. Do not register again after `access_denied`. 5. On success `access_token` is a named agent key (`dwk_`) for that shop, shown once. Call me.get before you say you are connected. `persistence` is `not_proven`. Doing Work does not keep a copy you can fetch later. The owner can revoke the key. Not offered: `identity_assertion` (no issuers are trusted, you get `issuer_not_enabled`) and an events endpoint. ## What you can call - REST: https://doingwork.work/v1, described by https://doingwork.work/v1/openapi.json. Send `Doing-Work-Version: 2026-11-01`. Writes accept an `Idempotency-Key` header. - MCP: https://doingwork.work/mcp (streamable HTTP). `tools/list` returns every tool you may call. - A2A: https://doingwork.work/a2a (JSON-RPC, A2A 1.0), described by https://doingwork.work/.well-known/agent-card.json. Send `SendMessage` with one data part, `{"op": "", "input": {...}}`, using a named agent key. There is no model behind it: the op runs exactly as on REST and MCP, with the same scopes, permissions and owner approvals. A held write comes back as an input required task; call `GetTask` later for the decision. Each `messageId` runs once. Some actions only run on a hosted page a person opens, such as signing a quote or paying an invoice. Those are marked `x-human-only` in the OpenAPI file and are never MCP tools. ## Errors Every error is JSON with `code`, `message` and `status`. A 429 comes with `Retry-After`.