Authentication

Docket uses OAuth authorization code flow with PKCE S256. A client acts as the person who approved it, within both that person’s grants and the scopes on its token.

Discover the resource first

The REST protected resource is https://api.clearthedocket.com/v1. Fetch its metadata from https://api.clearthedocket.com/.well-known/oauth-protected-resource/v1. The MCP resource remains https://api.clearthedocket.com/mcp and keeps its MCP protected-resource metadata path. The authorization-server issuer is https://api.clearthedocket.com/api/auth. Fetch its RFC 8414 metadata before constructing authorization requests. The discovered endpoints are:

Purpose	Endpoint
Dynamic client registration	`POST /api/auth/oauth2/register`
Browser authorization	`GET /api/auth/oauth2/authorize`
Token exchange and refresh	`POST /api/auth/oauth2/token`
Revocation	`POST /api/auth/oauth2/revoke`
Signing keys	`GET /api/auth/jwks`

Use only authorization_code and refresh_token grants. Docket does not issue client-credentials tokens or API keys.

Request the smallest scope

Scope	Consent text
`work:read`	View workspace structure, work, comments, updates, search, saved views, schedules, calendars, time, and your notifications.
`work:write`	Create and update work, comments, plans, schedules, time records, notification read state, and published brief content.
`agents:run`	Start, steer, resume, and cancel Athena or agent sessions, use voice sessions, and approve or reject proposed actions.
`connectors:link`	Connect, configure, disconnect, and run integrations with other tools you use.
`offline_access`	Keep working on your behalf without asking you to sign in again.

offline_access allows refresh tokens. It does not grant access to another resource. A work:read REST token currently authorizes only GET and HEAD /v1/orgs; it does not authorize task creation or other business REST routes.

Handle authority changes

Docket invalidates authority immediately when a person revokes a client, reduces consented scopes, disables the client, loses the user record, or loses a live grant. On 401 or insufficient_scope, stop the request and send the person through authorization again. Do not retry with a wider scope without their approval.

What Docket does not provide

Docket has no published SDK, no long-lived static credentials, and no outbound webhooks. Use OAuth discovery and your language’s standards-based OAuth and MCP clients.

​Discover the resource first

​Request the smallest scope

​Handle authority changes

​What Docket does not provide

Discover the resource first

Request the smallest scope

Handle authority changes

What Docket does not provide