# OAuth and OIDC provider

Each environment can act as a full OAuth 2.1 and OpenID Connect authorization server for your users. Use it when other applications (your own mobile app, partner integrations, AI agents) need access to your API on a user's behalf.

## Issuer and discovery

The issuer is `https://login.ohauthcat.com/oauth/<environment id>`. It differs from the end-user and SSO issuers, so no other kind of OhAuthCat token is accepted in its place. Clients discover everything from `/.well-known/openid-configuration` or `/.well-known/oauth-authorization-server` under the issuer.

| Endpoint under the issuer               | Standard                                       |
| --------------------------------------- | ---------------------------------------------- |
| `GET /authorize`                        | Authorization code + PKCE                      |
| `POST /token`                           | Code, refresh, client credentials, device code |
| `POST /revoke`                          | RFC 7009                                       |
| `POST /introspect`                      | RFC 7662 (confidential clients)                |
| `GET` or `POST /userinfo`               | OIDC Core                                      |
| `POST /device_authorization`, `/device` | RFC 8628 device flow                           |
| `POST /register`, `/register/<client>`  | RFC 7591 and 7592                              |
| `GET /jwks`                             | Signing keys                                   |

## Rules the server enforces

- PKCE with S256 on every authorization code; codes are single-use.
- Exact redirect URI match. Loopback redirects (`http://127.0.0.1`) match on any port, for native apps.
- `iss` in every authorization response (RFC 9207).
- One resource per access token (RFC 8707 `resource`); the token's `aud` is that resource, so a token for API A is refused at API B.
- Refresh tokens last 30 days and rotate on each use. Presenting a used one revokes the whole grant.

Access tokens are RFC 9068 JWTs (`typ: at+jwt`, ES256) with `iss`, `sub`, `aud`, `client_id`, `scope`, `jti`, `env`, `grant_id`, `org_id` and `auth_time`. Your API should check the signature against `/jwks`, the issuer, the exact audience and the expiry.

## Register clients and APIs

- `POST /v1/oauth/clients` registers a connected app: `confidential` or `public`, redirect URIs, grant types, scopes, consent text, logo and whether it is `third_party`. A confidential client's secret is shown once; `POST /v1/oauth/clients/{client}/secret` rotates it, keeping the old one valid for 24 hours.
- `POST /v1/oauth/resources` registers an API or an [MCP server](/oauth-provider/mcp/) with its scopes and token lifetime (60 to 3600 seconds).
- `PUT /v1/oauth/scopes/{scope}` defines a scope and the text the consent screen shows for it.

These need `oauth:read` or `oauth:write`. Events: `oauth_client.created`, `oauth_client.updated`, `oauth_client.secret_rotated`, `oauth_client.deleted`, `oauth_grant.created`, `oauth_grant.updated` and `oauth_grant.revoked`.

## Grants and organizations

A grant is a user's remembered consent for one client. `GET /v1/oauth/grants` lists them and `DELETE /v1/oauth/grants/{grant}` revokes one; users can also remove connected apps on the hosted account page. `PUT /v1/organizations/{org}/oauth_settings` lets an organization refuse third-party apps: its members' sign-ins to them answer `access_denied`, their existing third-party grants are revoked and refreshes stop ([`oauth_third_party_denied`](/errors/oauth_third_party_denied/)).

## Sign out of a connected app

`GET` or `POST /oauth/<environment>/logout` is OpenID RP-initiated logout, advertised as `end_session_endpoint` in that issuer's discovery document. Send `id_token_hint` (an ID token the environment issued to one of its clients; an expired one is accepted), and optionally `post_logout_redirect_uri` and `state`. The redirect URI must exactly match one of the client's `post_logout_redirect_uris` (set on `POST /v1/oauth/clients` or through dynamic client registration; at most 20, the redirect URI rules apply) before anything ends. OhAuthCat then deletes that client's refresh tokens for the session, ends the hosted session and returns to the URI with your `state`. ID tokens carry `sid`, the session ID. Audit event: `oauth_client.logout`.

Not available yet: pushed authorization requests (PAR), DPoP, front-channel and back-channel logout.
