# OAuth Reference

TaskRatchet runs an OAuth 2.1 authorization server so a third-party app or agent can act on a user's account — creating, completing, and managing their tasks — without ever seeing the user's password or personal API key.

Building tooling for yourself only? Use a personal [API Token](https://app.taskratchet.com/settings) instead and skip OAuth entirely — see the [API Reference](/api-reference.html). OAuth is for building something *other people* will authorize.

This page covers the flow and its design decisions. For exact request/response shapes, see the [OpenAPI spec](https://api.taskratchet.com/api2/openapi.json) — it's the source of truth and changes independently of this page.

## Flow

1. **Register your client** — `POST /oauth/register` ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591) Dynamic Client Registration). No approval process: give it your `redirect_uris` and you get back a `client_id`. Public clients only — no client secret, `token_endpoint_auth_method: "none"`.
2. **Send the user to `/oauth/authorize`** with your `client_id`, `redirect_uri`, requested `scope`, and a PKCE `code_challenge` (`S256`, required). The implicit flow (`response_type=token`) isn't supported.
3. **The user approves** — they log in if needed and see a consent screen listing exactly what you're asking for, scope by scope.
4. **Exchange the code for tokens** the standard OAuth 2.1 way. Access tokens are deliberately short-lived (15 minutes) so revocation actually means something — use your refresh token rather than trying to hold onto one. Refresh tokens rotate: each refresh invalidates the old one and issues a new one, so hold onto only the latest.

## Scopes

| Scope | Grants |
| --- | --- |
| `tasks:read` | List and read the user's tasks |
| `tasks:complete` | Mark tasks complete or incomplete |
| `tasks:write` | Create and edit tasks (edits can only make a task harder — later deadline never, higher stake or earlier deadline only) |
| `tasks:uncle` | Give up on a task early ("uncle"), triggering its charge immediately |

There's no `tasks:delete` — end users can't delete tasks through any interface, agents included.

## Discovery

- `GET /oauth/.well-known/oauth-authorization-server`
- `GET /oauth/.well-known/jwks.json`

The metadata document's own `authorization_endpoint`/`token_endpoint`/`jwks_uri` fields currently omit the `/oauth` prefix — hardcode the paths above rather than trusting the document's URLs.

## Revocation

Users can revoke a client's access at any time from [Connected Apps](https://app.taskratchet.com/settings/connected-apps) in their settings. This immediately kills the refresh token; an already-issued access token keeps working until it naturally expires (up to 15 minutes).

## Consent requirement

Whatever you build, never create, modify, or complete a task without the user's explicit, in-the-moment consent for that action — a task's stake is real money. A standing arrangement the user has explicitly set up in advance is the only exception.