API OAuth2 / OpenID Connect — Documentation API DSP2

Realm Keycloak. Flow Authorization Code (approche REDIRECT). Pas de client_secret : l'auth se fait par mTLS (sauf GET /auth, cf. « Particularités »).

Rappel hosts (cf. « Base URLs complètes par endpoint ») : GET /auth est sur auth.pro.lcl.fr (sans mTLS), tandis que POST /token et POST /revoke sont sur le host mTLS (psd-pro.lcl.fr en prod, sandbox-psd-pro.lcl.fr en sandbox). Tous portent le path /realms/{realm}/protocol/openid-connect/….

Flow d'autorisation complet

sequenceDiagram
    participant TPP as TPP Backend
    participant PSU as Navigateur PSU
    participant KC as Keycloak (IdP)
    participant API as API PSD2

    TPP->>PSU: Redirect vers /auth (response_type=code, client_id, redirect_uri, scope, state)
    PSU->>KC: GET /auth
    KC-->>PSU: Login + SCA + écran de consentement
    PSU->>KC: Credentials
    KC-->>PSU: 302 redirect_uri?code=...&state=...
    PSU-->>TPP: Code d'autorisation (via redirect)
    TPP->>KC: POST /token (grant_type=authorization_code, client_id, code, redirect_uri) [mTLS]
    KC-->>TPP: access_token + refresh_token
    TPP->>API: Appel API PSD2 avec access_token (Bearer)

Scopes demandables

Vous devez impérativement demander le scope openid pour obtenir un token utilisateur complet. Puis, selon vos besoins :

Scope	Description	Pré-requis certificat
`aisp`	Account Information Service Provider	Rôle `AIS` / pays `FR`
`extended_transaction_history`	Historique de transactions au-delà de la fenêtre standard (add-on AISP)	Rôle `AIS`

Conformément à STET §3.4.3.3, les rôles aisp / pisp / cbpii ne doivent pas être mélangés dans une même demande de scope. Un scope demandé sans le rôle correspondant dans le certificat est rejeté (scope_certificate_mismatch).

Demander aisp seul suffit. Vous n'avez besoin de demander, au POST /register (ou au PATCH), que vos scopes métier : aisp, et le cas échéant extended_transaction_history. La plateforme se charge du reste.

Modifier les scopes d'un client existant. Vous pouvez désormais mettre à jour les scopes d'un client OAuth déjà enregistré via PATCH /psd2/register/{clientId} (champ scope) — sans avoir à recréer le client.

Scopes système ré-injectés automatiquement (basic, offline_access). Sous le capot, nos systèmes utilisent basic et offline_access (et openid). Vous les verrez donc toujours en retour dans la réponse des tokens et sur le GET /psd2/register/{clientId}, quels que soient les scopes demandés.

Vous n'avez pas besoin de les demander au register / patch.

Si vous les envoyez quand même, c'est accepté sans erreur.

Exemple : demander openid aisp (ou même aisp seul) → scope accordé openid basic offline_access aisp. Seuls aisp et extended_transaction_history conditionnent vos accès métier ;