OAuth 2.0
Caledee supports the OAuth 2.0 Authorization Code flow with PKCE so third-party applications can access user data with explicit consent.
Issuing and using OAuth tokens is part of the Team plan. Create an app at Settings → Developers.
Endpoints
| Endpoint | Method | Description |
|---|---|---|
| /oauth/authorize | GET | Authorization + consent screen |
| /oauth/token | POST | Exchange code for tokens / refresh |
| /oauth/revoke | POST | Revoke a token (RFC 7009) |
| /oauth/userinfo | GET | OpenID Connect user profile |
| /oauth/register | POST | Dynamic Client Registration (RFC 7591) — public clients |
| /.well-known/oauth-authorization-server | GET | Server metadata discovery (RFC 8414) |
| /.well-known/oauth-protected-resource | GET | Resource metadata for MCP clients (RFC 9728) |
Dynamic Client Registration
MCP clients and other PUBLIC apps can self-register — no developer account needed.POST /oauth/register with client_name and redirect_uris (https only; plain http allowed for localhost) returns a client_id. No client secret is issued: registered clients are public, must use PKCE S256, and refresh tokens rotate on every use. Rate-limited; the consent screen marks these apps as unverified.
Authorization flow
- Redirect the user to
/oauth/authorizewith yourclient_id,redirect_uri,scope,state, and PKCEcode_challenge. - The user sees a consent screen showing your app name and requested permissions.
- On approval, Caledee redirects back to your
redirect_uriwith a short-livedcode. - Exchange the code at
POST /oauth/tokenwith yourcode_verifier(PKCE) to get an access token + refresh token. - Use the access token as a Bearer token in API requests.
Scopes
| Scope | Description |
|---|---|
| read:profile | View name, email, timezone |
| read:bookings | List and view bookings |
| write:bookings | Create, cancel, reschedule bookings |
| read:event-types | List and view event types |
| write:event-types | Create and edit event types |
| read:availability | View schedules and rules |
| write:availability | Edit schedules and block dates |
Token lifecycle
- Access token: 1 hour TTL. Use as
Authorization: Bearer <token>. - Refresh token: 30 days TTL. Use
grant_type=refresh_tokenat/oauth/tokento get a new pair. - Refresh rotates both tokens — the old pair is revoked.
PKCE (required for public clients)
Public clients (SPAs, mobile apps, Claude Desktop) must use PKCE with the S256 method. Generate a random code_verifier, compute code_challenge = base64url(sha256(verifier)), and include both in the flow.
Error responses
Token endpoint errors follow RFC 6749 §5.2: {"error": "invalid_grant"} with standard error codes (invalid_request, invalid_client, invalid_grant,unsupported_grant_type).