API authentication, from personal tokens to OAuth 2 with PKCE
A personal token for your own tools, an OAuth app to act on behalf of other accounts. Both go in the x-api-key header.
The API takes two kinds of tokens, always in the x-api-key header: the personal token for your own scripts, and the OAuth access token, obtained through OAuth 2 with PKCE when your app acts for other people. The Authorization header is not read.
Personal tokens and scopes
A member creates tokens in Settings › Integrations (Pro plan): a name, an optional expiry date and scopes. Tokens start with rdv_pat_, are shown once, and act on behalf of their member with their role's rights. Scopes: utilisateur:lire, organisation:lire, organisation:administrer, types:lire, types:ecrire, disponibilites:lire, disponibilites:ecrire, reservations:lire, reservations:ecrire, liens:ecrire, webhooks:ecrire, journal:lire, donnees:effacer. The reference gives the scope of each route.
OAuth 2 with PKCE, step by step
- The owner declares the app in Settings › Integrations › OAuth apps: name, redirect URIs, allowed scopes. You get a
client_id(rdv_app_…) and a secret (rdv_cs_…). - Prepare PKCE (S256 only) and a
state:
CODE_VERIFIER=$(openssl rand -hex 32)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n')- Send the user to
https://your-application-domain/oauth/autoriser?response_type=code&client_id=…&redirect_uri=…&scope=types%3Alire&state=…&code_challenge=…&code_challenge_method=S256. They come back with?code=rdv_code_…&state=…. - Exchange the code (valid 10 minutes, single use), secret in the body:
curl -X POST "https://your-application-domain/api/webhooks/oauth/token" \
-d grant_type=authorization_code -d code=rdv_code_… \
-d redirect_uri=https://example.com/oauth/callback -d code_verifier="$CODE_VERIFIER" \
-d client_id=rdv_app_… -d client_secret=rdv_cs_…You get rdv_oat_… (2 hours) and rdv_ort_… (90 days). Send the access token in x-api-key.
Refresh, revoke, introspect
Refresh with grant_type=refresh_token: each refresh returns a new pair and retires the old one; reusing an old refresh token stops the app's access. Revoke with POST /api/webhooks/oauth/revoke, inspect with POST /api/webhooks/oauth/introspect (RFC 7662). The RFC 8414 metadata is at /.well-known/oauth-authorization-server, and GET /api/v1/users/me is the userinfo endpoint. Until client_id and client_secret are right, these calls answer 404; then OAuth 2 errors such as invalid_grant. See also platform integration and limits and errors.
Declare your OAuth app
Create your account, switch to Pro and declare your app in Settings › Integrations.
Create my account