# OAuth

> Let your app act for a Wapitick user with OAuth 2.1, PKCE and refresh tokens.

Use OAuth when your app acts for someone else's Wapitick business (a marketplace app, an AI tool, a plugin). For your
own business, an [API key](/quickstart) is simpler.

## Endpoints

The authorization server is the API host, `https://api.wapitick.com`. Its metadata is at
`/.well-known/oauth-authorization-server` (also `/.well-known/openid-configuration`).

| Endpoint | Path |
|---|---|
| Authorize | `GET /oauth/authorize` |
| Token | `POST /oauth/token` |
| Register a client (RFC 7591) | `POST /oauth/register` |
| Revoke | `POST /oauth/revoke` |
| Introspect | `POST /oauth/introspect` |
| Signing keys | `GET /oauth/jwks.json` |

## Flow

1. Send the user to `/oauth/authorize` with `response_type=code`, your `client_id`, `redirect_uri`, `scope`, `state`,
   `code_challenge` and `code_challenge_method=S256`. PKCE is required. Add `resource` (RFC 8707) to choose what the
   token is for: the API (`https://api.wapitick.com`) or the [MCP server](/mcp).
2. The user signs in to Wapitick, picks a business, and approves. They can only grant what their role allows.
3. Exchange the `code` at `/oauth/token`. You get an access token (`wko_...`, about an hour) and a refresh token.
4. Call the API with `Authorization: Bearer wko_...`.

Refresh tokens rotate on every use. If an old refresh token is used again, the whole grant is revoked, so store the new
one each time. Grants also include `client_credentials` for confidential clients.

## Scopes

Scopes are the same as API key scopes, listed per operation in the [API reference](/reference). One token covers one
business. Every request is checked against the grant and the user's current role, so removing someone's access takes
effect within 30 seconds.

Errors are [problem codes](/errors), for example [`invalid_token`](/errors/invalid_token) and
[`insufficient_scope`](/errors/insufficient_scope).
