---
title: "OAuth & scopes"
description: "How to connect to Cadae with OAuth 2.0 and PKCE: client registration, consent, token exchange, refresh, revocation and scopes."
language: en-GB
canonical: https://cadae.ai/en-GB/docs/oauth
---

# OAuth & scopes

How to connect to Cadae with OAuth 2.0 and PKCE: client registration, consent, token exchange, refresh, revocation and scopes.


Cadae is an OAuth 2.0 provider. Third-party clients — MCP clients, your own
tools — get per-user access through the authorisation-code flow with PKCE.

## The flow

1. **Register** a client: `POST /oauth/register` with your `redirect_uris`
   and requested `scope` (dynamic client registration, RFC 7591).
2. **Authorise**: open `GET /oauth/authorize?…` — the user lands on the
   consent page, picks a Portfolio and approves. Requested scopes are
   downscoped automatically by the granter's access in that Portfolio — the
   consent page says the same: *Permissions are limited by your role in the
   Portfolio.*
3. **Exchange**: `POST /oauth/token` with the code and your `code_verifier`
   (S256). You receive `cad_at_…` (2h) and `cad_rt_…` (30d).
4. **Refresh**: the same endpoint with `grant_type=refresh_token` — pairs
   rotate; the old pair dies immediately.
5. **Revoke**: `POST /oauth/revoke` (RFC 7009).

Codes are single-use; a replay revokes everything derived from the code
(RFC 9700). Only S256 PKCE is accepted.

## Discovery

- `/.well-known/oauth-authorization-server` (RFC 8414)
- `/.well-known/oauth-protected-resource` and `/…/mcp` (RFC 9728)

## Scopes

Same catalogue as the API: `viewer.read`, `organisation.read|write`,
`hotel.read|write`, `members.read|write`, `invites.write`, `activities.read`,
`notifications.read`, plus the `apis.all` / `apis.read` aliases.

## Personal and Portfolio tokens

For non-interactive automation, skip OAuth: create a personal token
(`cad_pat_…`) or a Portfolio token (`cad_osk_…`) in **Settings → Developer**.