TaskRatchet

Appearance

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 instead and skip OAuth entirely — see the API Reference. 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 — it's the source of truth and changes independently of this page.

Flow ​

  1. Register your client — POST /oauth/register (RFC 7591 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 ​

ScopeGrants
tasks:readList and read the user's tasks
tasks:completeMark tasks complete or incomplete
tasks:writeCreate and edit tasks (edits can only make a task harder — later deadline never, higher stake or earlier deadline only)
tasks:uncleGive 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 in their settings. This immediately kills the refresh token; an already-issued access token keeps working until it naturally expires (up to 15 minutes).

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.