Bob le développeur
Estimer

Intégrer Pro Santé Connect : le guide technique complet (2026)

Antoine Auffray

07/04/2026 · Mis à jour le 17/11/2026

Depuis le 1er janvier 2023, Pro Santé Connect est obligatoire pour les services numériques en santé dits « sensibles », une catégorie qui couvre la plupart des logiciels partagés entre professionnels. Pourtant, en cherchant un guide d'intégration technique en français, on ne trouve que la documentation officielle de l'ANS, dense et dispersée sur plusieurs portails.

Chez Bob le développeur, on intègre PSC sur des projets e-santé depuis plusieurs années. Cet article rassemble tout ce qu'on aurait aimé trouver à l'époque : le flow OIDC complet, les endpoints exacts (sandbox et production), le parsing des claims RPPS, une implémentation NestJS, et surtout les pièges qui font perdre des semaines quand on ne les connaît pas.

L'essentiel en 30 secondes :

  • PSC utilise OpenID Connect (Authorization Code Flow) avec des spécificités santé
  • L'endpoint Authorize a un host différent des autres endpoints
  • Le paramètre acr_values doit valoir eidas1 (pas eidas2)
  • Le numéro RPPS se trouve dans le SubjectNameID, préfixé par 8
  • Depuis mars 2026, le sub est un UUID technique sans lien avec le RPPS
  • L'Annuaire Santé sert à gérer les habilitations métier, pas à revérifier le droit d'exercice

Qu'est-ce que Pro Santé Connect et pourquoi c'est obligatoire ?

Pro Santé Connect (PSC) est le fédérateur d'identité sectoriel de la santé en France. Opéré par l'Agence du Numérique en Santé (ANS) et ouvert en 2019, il permet aux professionnels de s'authentifier sur les services numériques avec leurs moyens d'identification professionnels : la carte CPS physique et l'application mobile e-CPS, auxquelles la mire de connexion ajoute aujourd'hui la clé de sécurité FIDO2 et la délégation à un fournisseur d'identité tiers. Les certificats logiciels de l'IGC-Santé ont un autre rôle : ils authentifient votre serveur auprès de PSC, en mTLS.

PSC se distingue de FranceConnect sur un point fondamental : FranceConnect authentifie les citoyens (vos patients), PSC authentifie les professionnels de santé (médecins, pharmaciens, infirmiers). Les deux reposent sur OpenID Connect, mais PSC ajoute des claims spécifiques au secteur santé, notamment le numéro RPPS et le rôle professionnel.

Deux arrêtés du printemps 2022 fixent le cadre. Celui du 28 mars 2022 rend opposable le référentiel d'identification électronique de la PGSSI-S, dont l'exigence 4 impose aux services « sensibles » d'avoir implémenté Pro Santé Connect au 1er janvier 2023 au plus tard. Celui du 4 avril 2022 encadre Pro Santé Connect et la e-CPS, et approuve le référentiel PSC (version 1.8.4), opposable à tout fournisseur de service qui s'y raccorde.

Un service est « sensible » s'il traite des données de santé à caractère personnel et entre dans au moins une de ces catégories :

  • les services partagés, qui dépassent le cadre d'une personne morale ou sont déployés à l'échelle d'un territoire ou du pays (DMP, plateforme de e-parcours, dossier pharmaceutique) ;
  • les services qui intègrent un service partagé (dossier patient informatisé, système de gestion de laboratoire, système d'information de radiologie, messagerie sécurisée de santé) ;
  • les services qui offrent un accès web externe au système d'information, pour les professionnels d'un établissement ou leurs correspondants de ville ;
  • les services de grande échelle : plus de 10 000 patients nouvellement référencés par an, ou plus de 1 000 professionnels distincts qui s'identifient par an.

Une plateforme de téléconsultation ou de coordination des soins utilisée par des professionnels de plusieurs structures dépasse le cadre d'une personne morale : elle relève de la première catégorie. Pour les services qui n'entrent dans aucune, les exigences du référentiel valent recommandations.

Cette distinction devrait disparaître. Le projet de nouvelle version du référentiel, notifié à la Commission européenne le 14 septembre 2026 et pas encore adopté au 17 novembre 2026, impose à tout service numérique en santé utilisé par des professionnels de permettre la connexion par Pro Santé Connect. Une connexion maison peut s'y ajouter, avec une attestation de conformité au plus tard le 31 décembre 2026 pour les services déjà en production. Notre test authentification santé dit en deux minutes où se situe votre service.


Le flow OpenID Connect de PSC en 11 étapes

PSC implémente le standard OpenID Connect 1.0 avec un Authorization Code Flow. Le processus est similaire à ce que vous connaissez avec FranceConnect ou tout autre provider OIDC, mais avec quelques spécificités à respecter.

Diagramme du flow complet

Navigateur          Votre Backend           PSC (ANS)          Annuaire Santé
    │                     │                     │                     │
    │  1. Clic "Se        │                     │                     │
    │  connecter PSC"     │                     │                     │
    │────────────────────>│                     │                     │
    │                     │  2. Redirect avec   │                     │
    │                     │  state + nonce      │                     │
    │<─ ─ ─ ─ ─ ─ ─ ─ ─ ─│────────────────────>│                     │
    │                     │                     │                     │
    │  3. Choix CPS ou e-CPS                    │                     │
    │  4. Authentification du médecin           │                     │
    │                     │                     │                     │
    │  5. Callback avec   │                     │                     │
    │  ?code=xxx&state=yyy│                     │                     │
    │────────────────────>│                     │                     │
    │                     │  6. Échange code    │                     │
    │                     │  → access_token     │                     │
    │                     │────────────────────>│                     │
    │                     │<────────────────────│                     │
    │                     │                     │                     │
    │                     │  7. GET /userinfo   │                     │
    │                     │────────────────────>│                     │
    │                     │<────────────────────│                     │
    │                     │  8. Claims RPPS     │                     │
    │                     │                     │                     │
    │                     │  9. Requête FHIR ──────────────────────>  │
    │                     │  10. PractitionerRole  <────────────────  │
    │                     │                     │                     │
    │  11. Session créée  │                     │                     │
    │<────────────────────│                     │                     │

Paramètres de la requête /authorize

Paramètre Valeur Rôle
response_type code Authorization Code Flow
client_id Fourni par l'ANS Identifie votre service
redirect_uri Votre URL de callback Strictement identique à celle déclarée au raccordement
scope openid scope_all Exigé par le référentiel (EXI PSC 17)
acr_values eidas1 Valeur requise par PSC (EXI PSC 16)
state Aléatoire, recommandé Protection anti-CSRF
nonce Aléatoire, recommandé Protection anti-rejeu

Un point qui surprend souvent les développeurs venant de FranceConnect : le paramètre acr_values doit valoir eidas1, pas eidas2. C'est la seule valeur acceptée : l'ANS indique qu'à ce jour toutes les authentifications délivrées par Pro Santé Connect sont de niveau eIDAS 1, et que la prise en charge du niveau 2 est en préparation. Pour connaître le niveau du moyen réellement utilisé, lisez le claim auth_level, présent dans les jetons depuis avril 2026 : "1" correspond au niveau Standard (eIDAS faible), "2" au niveau Certifié (trajectoire eIDAS substantiel). Seule une e-CPS rehaussée avec France Identité atteint aujourd'hui le niveau 2. La carte CPx, la clé FIDO2 et la délégation restent au niveau 1.

Quatre contraintes encadrent ce flux :

  • Ni iframe, ni CORS. La mire PSC s'affiche en pleine page et l'échange du code reste côté serveur.
  • Pas de webview dans une application native. Le référentiel classe les applications mobiles et de bureau parmi les « clients lourds » et leur impose d'ouvrir un navigateur extérieur à l'application (EXI PSC 25 et 26). L'autre voie est le flux CIBA, que PSC propose depuis juin 2022.
  • Pas de Pushed Authorization Requests. L'endpoint figure dans le document de découverte mais n'est pas activé. Désactivez PAR si votre client OIDC l'utilise par défaut.
  • Un paramètre iss dans le callback, en plus de code et state.

Endpoints PSC : sandbox et production

PSC est hébergé sur une infrastructure Keycloak, ce qui explique le pattern d'URLs /auth/realms/esante-wallet/. L'ANS met à disposition deux environnements : le BAS (Bac À Sable) pour l'intégration et la production.

Environnement BAS (sandbox)

Endpoint URL
Discovery https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/.well-known/wallet-openid-configuration
Authorize https://wallet.bas.psc.esante.gouv.fr/auth
Token https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token
UserInfo https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/userinfo
Logout https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/logout

Environnement Production

Endpoint URL
Discovery https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/.well-known/wallet-openid-configuration
Authorize https://wallet.esw.esante.gouv.fr/auth
Token https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token
UserInfo https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/userinfo
Logout https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/logout

L'endpoint Authorize utilise un host différent (wallet.*) des autres endpoints (auth.*). C'est une source d'erreurs fréquente quand on recopie les URLs en ne changeant que le chemin.

Le piège se prolonge dans la découverte automatique. Le document à utiliser est wallet-openid-configuration, celui que documente l'ANS. L'URL standard .well-known/openid-configuration répond elle aussi, mais elle annonce un endpoint d'autorisation sur auth.* au lieu de wallet.*. Si votre librairie se configure seule à partir de l'issuer, vérifiez quelle URL elle a retenue.

Autre subtilité : le sous-domaine sandbox est bas.psc et non bas.esw. On trouve encore des documentations tierces qui utilisent bas.esw, un domaine qui ne se résout pas.


Décoder les claims PSC : RPPS, SubjectRole et SubjectNameID

L'appel au endpoint /userinfo retourne un ensemble de claims spécifiques au secteur santé. Avec le scope openid scope_all, voici la structure de la réponse (extrait, valeurs fictives) :

{
  "sub": "0b6f5d2e-3c1a-4a7e-9a55-2f1f6f0c9d11",
  "SubjectNameID": "8{RPPS}",
  "preferred_username": "8{RPPS}",
  "PSISubjectNameID": "",
  "auth_level": "1",
  "codeCivilite": "MME",
  "given_name": "Marie",
  "family_name": "MARTIN",
  "SubjectOrganization": "CABINET DR MARTIN",
  "SubjectOrganizationID": "{identifiant de la structure}",
  "SubjectRole": [
    "10^1.2.250.1.213.1.1.5.5"
  ],
  "Secteur_Activite": "SA07^1.2.250.1.71.4.2.4",
  "Palier_Authentification": "APPPRIP3^1.2.250.1.213.1.5.1.1.1",
  "PSI_Locale": "1.2.250.1.213.1.3.1.1",
  "UITVersion": "1.0",
  "otherIds": [
    {
      "identifiant": "8{RPPS}",
      "origine": "RPPS",
      "qualite": 1
    }
  ],
  "SubjectRefPro": {
    "exercices": [
      {
        "codeProfession": "10",
        "codeCategorieProfessionnelle": "C",
        "codeTypeSavoirFaire": "S",
        "codeSavoirFaire": "SM54",
        "activities": [...]
      }
    ]
  }
}

Le SubjectNameID : extraire le numéro RPPS

Le SubjectNameID porte l'identifiant national du professionnel, au format {chiffre du type}{identifiant}. Le premier chiffre indique le type d'identifiant :

Préfixe Signification
8 Numéro RPPS (11 chiffres)
0 Numéro ADELI, bientôt déprécié
3 Identifiant local rattaché à un FINESS
5 Identifiant local rattaché à un SIRET

Pour une application de téléconsultation, vous attendez un SubjectNameID commençant par 8. Les onze chiffres restants constituent le numéro RPPS du professionnel. Le référentiel PSC impose d'ailleurs ce champ comme identifiant unique de l'identité, à reporter dans votre traçabilité (EXI PSC 18).

Deux cas méritent un test. Un professionnel qui s'authentifie avec une carte porteuse d'un identifiant ADELI ou local n'aura pas de RPPS dans SubjectNameID : cherchez alors dans otherIds l'entrée dont l'origine vaut RPPS. Et le champ peut être vide pour un utilisateur qui ne possède qu'une identité Pro Santé Identité, détaillée plus bas.

Attention : n'utilisez pas le claim sub comme identifiant métier. Depuis le 19 mars 2026 en production, c'est un UUID technique sans rapport avec le RPPS.

Le SubjectRole : vérifier la profession

Le claim SubjectRole est un tableau de chaînes au format code^OID (deux champs séparés par ^).

Code Profession
10 Médecin
21 Pharmacien
40 Chirurgien-dentiste
50 Sage-femme
60 Infirmier
70 Masseur-kinésithérapeute

PSC authentifie tous les professionnels enregistrés à l'Annuaire Santé. Si votre application est réservée aux médecins, c'est à vous de filtrer sur le code 10. SubjectRole reprend le rôle de l'une des activités du professionnel. La liste complète de ses exercices, avec un codeProfession par exercice, se trouve dans SubjectRefPro.exercices : c'est elle qu'il faut parcourir pour un contrôle d'accès.

Les autres scopes disponibles

Le référentiel demande openid scope_all, qui retourne l'ensemble des claims. La documentation décrit aussi des scopes plus fins :

Scope Claims obtenus dans le UserInfo
openid sub
profile codeCivilite, given_name, family_name
rpps SubjectRefPro, SubjectNameID
interop SubjectOrganization, SubjectOrganizationID, SubjectRole, SubjectNameID, PSI_Locale, palier d'authentification et champs techniques
referentiel SubjectNameID, otherIds
scope_all Tout le contenu du UserInfo

Implémentation NestJS pas à pas

L'intégration dans un backend NestJS repose sur Passport avec une strategy OIDC.

1. La strategy Passport

// auth/strategies/psc.strategy.ts
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { PassportStrategy } from '@nestjs/passport';
import { Strategy } from 'passport-openidconnect';

// passport-openidconnect ne transmet le UserInfo brut, l'id_token et le
// refresh_token qu'à un callback de vérification à 9 arguments
const VERIFY_ARITY = 9;

interface PscUserInfo {
  SubjectNameID?: string;
  given_name?: string;
  family_name?: string;
  SubjectOrganization?: string;
  auth_level?: string;
  otherIds?: { identifiant: string; origine: string; qualite: number }[];
  SubjectRefPro?: { exercices?: { codeProfession: string }[] };
}

@Injectable()
export class ProSanteConnectStrategy extends PassportStrategy(
  Strategy,
  'psc',
  VERIFY_ARITY,
) {
  constructor(configService: ConfigService) {
    super({
      issuer: configService.get('PSC_ISSUER'),
      authorizationURL: configService.get('PSC_AUTHORIZATION_URL'),
      tokenURL: configService.get('PSC_TOKEN_URL'),
      userInfoURL: configService.get('PSC_USERINFO_URL'),
      clientID: configService.get('PSC_CLIENT_ID'),
      clientSecret: configService.get('PSC_CLIENT_SECRET'),
      callbackURL: configService.get('PSC_CALLBACK_URL'),
      // La librairie ajoute "openid" elle-même
      scope: 'scope_all',
      // acr_values=eidas1 requis par PSC (EXI PSC 16)
      acrValues: 'eidas1',
      nonce: true,
      skipUserProfile: false,
    });
  }

  async validate(
    issuer: string,
    userInfo: { _json: PscUserInfo },
    idTokenProfile: unknown,
    context: unknown,
    idToken: string,
    accessToken: string,
    refreshToken: string,
  ) {
    const claims = userInfo._json;
    const rppsNumber = this.extractRpps(claims);

    if (!rppsNumber) {
      throw new UnauthorizedException(
        'RPPS number not found in PSC response',
      );
    }

    // Vérifier que le professionnel exerce bien comme médecin (code 10)
    const professionCodes = (claims.SubjectRefPro?.exercices ?? []).map(
      (exercice) => exercice.codeProfession,
    );
    if (!professionCodes.includes('10')) {
      throw new UnauthorizedException(
        'Only doctors (code 10) are authorized',
      );
    }

    return {
      rppsNumber,
      firstName: claims.given_name,
      lastName: claims.family_name,
      professionCodes,
      organization: claims.SubjectOrganization,
      authLevel: claims.auth_level,
      // À garder en session : id_token pour la déconnexion,
      // refresh_token pour prolonger la session PSC
      idToken,
      refreshToken,
    };
  }

  // Identifiant national = "8" + numéro RPPS à 11 chiffres
  private extractRpps(claims: PscUserInfo): string | null {
    const candidates = [
      claims.SubjectNameID,
      ...(claims.otherIds ?? [])
        .filter((id) => id.origine === 'RPPS')
        .map((id) => id.identifiant),
    ];
    const nationalId = candidates.find((id) => /^8\d{11}$/.test(id ?? ''));
    return nationalId ? nationalId.substring(1) : null;
  }
}

Trois détails de cette strategy tiennent à passport-openidconnect (version 0.1.2) plus qu'à PSC :

  • Le paramètre acr_values se règle avec l'option acrValues. La librairie ignore les options qu'elle ne connaît pas, sans erreur : une faute sur ce nom et la requête part sans acr_values.
  • Les claims santé ne sont pas dans le profil normalisé. Passport ne garde que l'identifiant, le nom et l'email. Le UserInfo complet se lit dans _json, et la librairie ne le transmet qu'à un callback de vérification à 9 arguments. C'est le rôle du troisième paramètre de PassportStrategy, qui fixe cette arité quelle que soit la signature de validate.
  • Le state est stocké en session. La strategy a besoin d'un middleware de session (express-session ou équivalent) actif sur les routes d'authentification.

Ce code a été exécuté contre un serveur de test qui reproduit les réponses documentées par l'ANS, avec @nestjs/passport 11 et 12. Il ne remplace pas vos tests en bac à sable, que le référentiel impose avant toute mise en production (EXI PSC 12).

Le référentiel recommande par ailleurs une implémentation certifiée par la fondation OpenID. passport-openidconnect n'en fait pas partie. En Node.js, la librairie openid-client est certifiée : c'est l'option à retenir si vous n'êtes pas attaché à Passport.

2. Les variables d'environnement

# Pro Santé Connect, Sandbox (BAS)
PSC_ISSUER=https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet
PSC_AUTHORIZATION_URL=https://wallet.bas.psc.esante.gouv.fr/auth
PSC_TOKEN_URL=https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token
PSC_USERINFO_URL=https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/userinfo
PSC_LOGOUT_URL=https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/logout
PSC_CLIENT_ID=your-psc-client-id
PSC_CLIENT_SECRET=your-psc-client-secret
PSC_CALLBACK_URL=https://your-app.example.com/auth/psc/callback

# Annuaire Santé (données métier du professionnel)
ANNUAIRE_SANTE_URL=https://gateway.api.esante.gouv.fr
ANNUAIRE_SANTE_API_KEY=your-gravitee-api-key

Notez que PSC_AUTHORIZATION_URL pointe vers wallet.bas.psc tandis que les autres endpoints utilisent auth.bas.psc. Cette différence est volontaire et doit être respectée.

3. Session, rafraîchissement et déconnexion

Les durées de vie sont courtes, et identiques en bac à sable et en production :

Élément Durée de validité
Code d'autorisation 1 minute
Access token 2 minutes
Refresh token 30 minutes
Session PSC 4 heures au maximum

La session PSC est globale à l'utilisateur et partagée entre les services raccordés : c'est ce qui lui évite de se réauthentifier en passant de l'un à l'autre. Elle expire après 30 minutes sans activité, et dans tous les cas au bout de 4 heures. Le référentiel vous demande donc de la rafraîchir tant que l'utilisateur est actif chez vous, et seulement dans ce cas (EXI PSC 11). Le rafraîchissement est un POST sur l'endpoint Token avec grant_type=refresh_token, le refresh_token, votre client_id et votre client_secret. L'ANS suggère de le déclencher quand l'utilisateur change de page ou de rubrique.

La déconnexion est une exigence (EXI PSC 20) : votre bouton doit fermer la session de votre service et celle de PSC. Elle passe par une redirection du navigateur vers l'endpoint Logout, avec l'id_token reçu au login dans id_token_hint et, si vous voulez ramener l'utilisateur chez vous, un post_logout_redirect_uri identique à l'URL déclarée au raccordement. Cette déconnexion vaut pour tous les services et appareils de l'utilisateur, et PSC ne notifie pas les autres services. À l'inverse, une déconnexion pour inactivité sur votre service ne doit pas fermer la session PSC (EXI PSC 32).


Exploiter l'Annuaire Santé (FHIR R4) pour les habilitations

Une idée circule beaucoup dans les articles techniques sur PSC : il faudrait recroiser le RPPS contre l'Annuaire Santé pour attraper les praticiens radiés qui passeraient encore l'authentification. Cette précaution part d'une méconnaissance de la chaîne de données.

PSC ne constitue pas un référentiel parallèle. Il s'appuie sur l'Annuaire Santé, lui-même alimenté par le RPPS et le FINESS. Quand un ordre professionnel prononce une radiation, la fiche RPPS est fermée et les moyens d'authentification associés (carte CPS, e-CPS) sont révoqués en amont. Le professionnel radié n'obtient plus de jeton PSC. Recroiser le active de l'Annuaire après coup revient donc à interroger la même source, une étape plus loin dans la chaîne.

L'API FHIR de l'ANS répond à un autre besoin, et celui-là est réel : récupérer les caractéristiques sectorielles du professionnel pour piloter vos habilitations. PSC vous donne une identité et un code profession. L'Annuaire vous donne les situations d'exercice, les savoir-faire, les spécialités et les structures de rattachement. C'est ce qui permet de répondre à des questions que PSC laisse ouvertes : ce cardiologue exerce-t-il bien dans l'établissement qui l'a invité sur la plateforme ? Ce pharmacien est-il rattaché à l'officine dont il demande le dossier ?

Le service d'enrichissement

L'ANS expose une API FHIR R4 sur le gateway gateway.api.esante.gouv.fr. Deux ressources vous intéressent : Practitioner porte l'identité et les qualifications (diplômes, exercices professionnels, savoir-faire), PractitionerRole porte les situations d'exercice (fonction, genre d'activité, mode d'exercice, structure de rattachement).

Un seul appel suffit à récupérer les deux, grâce au _revinclude :

// auth/services/annuaire-sante.service.ts
import { Injectable } from '@nestjs/common';
import { HttpService } from '@nestjs/axios';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class AnnuaireSanteService {
  constructor(
    private httpService: HttpService,
    private configService: ConfigService,
  ) {}

  /**
   * Récupère la fiche annuaire d'un professionnel et ses situations
   * d'exercice. Sert à alimenter les habilitations métier, pas à
   * contrôler le droit d'exercice (PSC s'en charge en amont).
   */
  async getProfile(rppsNumber: string) {
    const baseUrl = this.configService.get('ANNUAIRE_SANTE_URL');

    const response = await this.httpService.axiosRef.get(
      `${baseUrl}/fhir/v2/Practitioner`,
      {
        params: {
          identifier: rppsNumber,
          _revinclude: 'PractitionerRole:practitioner',
        },
        headers: {
          'ESANTE-API-KEY': this.configService.get('ANNUAIRE_SANTE_API_KEY'),
        },
      },
    );

    const resources = (response.data.entry ?? []).map((e) => e.resource);
    const practitioner = resources.find(
      (r) => r.resourceType === 'Practitioner',
    );
    const roles = resources.filter(
      (r) => r.resourceType === 'PractitionerRole',
    );

    return {
      // Diplômes, exercices professionnels et savoir-faire
      qualifications: (practitioner?.qualification ?? []).flatMap(
        (q) => q.code?.coding?.map((c) => c.code) ?? [],
      ),
      // Fonction, genre d'activité, mode d'exercice, structure
      situations: roles.map((role) => ({
        role: role.code?.[0]?.coding?.[0]?.code,
        organizationRef: role.organization?.reference,
        active: role.active,
      })),
    };
  }
}

Le _revinclude remonte les PractitionerRole mais pas les Organization qu'ils référencent. Si vous avez besoin du détail des structures, enchaînez avec GET /fhir/v2/PractitionerRole?practitioner={idTechnique}&_include=PractitionerRole:organization.

Ce que l'Annuaire vous apporte concrètement

Donnée Source Usage typique
Identité, RPPS, profession PSC (claims) Créer et rattacher le compte
Diplômes et savoir-faire Annuaire (Practitioner.qualification) Router vers les bons parcours de soin
Situations d'exercice Annuaire (PractitionerRole) Autoriser l'accès à un service précis
Structures de rattachement Annuaire (Organization) Cloisonner les données par établissement

Attention à la version d'API. L'API FHIR de l'Annuaire existe en v1 et en v2, et la v1 est en fin de vie : l'ANS annonce son décommissionnement pour janvier 2027. Partez directement sur /fhir/v2/. Trois points vous concernent au premier appel : le header d'authentification est ESANTE-API-KEY, le paramètre identifier accepte le numéro RPPS nu, et les identifiants techniques des ressources Practitioner et PractitionerRole ne correspondent pas entre les deux versions. Si vous les stockez en base, appuyez-vous sur l'identifiant métier plutôt que sur l'ID technique.

Les paramètres de recherche et les profils FHIR sont décrits dans le guide d'implémentation Annuaire Santé et la documentation de l'API. La clé API s'obtient sur portal.api.esante.gouv.fr.

Ces données évoluent lentement. Un cache de 24 heures par professionnel suffit largement, avec une invalidation au changement de structure côté métier.


Les 7 pièges qui font perdre des semaines aux développeurs

Après plusieurs intégrations PSC, voici les erreurs les plus fréquentes que nous avons rencontrées (ou évitées de justesse).

1. Confondre les sous-domaines sandbox. L'URL sandbox utilise bas.psc et non bas.esw. Certaines documentations tierces indiquent auth.bas.esw.esante.gouv.fr, ce qui retourne une erreur DNS. Le bon domaine est auth.bas.psc.esante.gouv.fr.

2. Mettre acr_values=eidas2 au lieu de eidas1. L'intuition dit « authentification forte, donc eidas2 », mais PSC n'accepte que eidas1. Le niveau réel du moyen utilisé se lit dans auth_level, pas dans ce paramètre.

3. Utiliser le sub comme identifiant RPPS. Le numéro RPPS se trouve dans SubjectNameID (préfixé par 8), pas dans sub. Depuis mars 2026, le sub est un UUID technique : une base construite dessus a vu tous ses comptes changer d'identifiant.

4. Oublier de vérifier la profession. PSC authentifie tous les professionnels de santé : médecins, pharmaciens, infirmiers, kinés. Si votre app est réservée aux médecins, vérifiez que le code profession est 10. Dans SubjectRole, le format est code^OID (deux champs, pas trois).

5. Croire que PSC suffit à gérer les habilitations. PSC vous authentifie un professionnel et vous donne son code profession. Il ne tranche pas l'accès à vos données : le référentiel le dit lui-même, les contrôles d'accès restent à votre charge. Si votre application cloisonne les données par établissement ou ouvre des fonctionnalités selon la spécialité, appuyez-vous sur l'Annuaire Santé. À l'inverse, ne codez pas de recroisement du champ active en pensant filtrer les praticiens radiés : ils ne franchissent déjà pas l'étape PSC.

6. Sous-estimer les délais administratifs. Le raccordement enchaîne quatre démarches, chacune avec un délai moyen de deux semaines selon l'ANS : compte iSC, Datapass, accès au bac à sable, accès à la production. Lancez les deux premières dès le début du projet pour que les délais courent en parallèle du développement.

7. Traiter l'access token comme une session. Il expire au bout de 2 minutes. Appelez le UserInfo tout de suite après l'échange du code, conservez le refresh token côté serveur et rafraîchissez tant que l'utilisateur est actif. Sans rafraîchissement, la session PSC tombe au bout de 30 minutes.


Évolutions 2026 : Pro Santé Identité (PSI)

Le déploiement de Pro Santé Identité (PSI) a modifié le contenu des jetons PSC en deux étapes, toutes deux en production.

Première étape (bac à sable le 29 janvier 2026, production le 19 mars 2026). Le champ sub change de nature. Il était composé de trois parties séparées par :, dont l'identifiant national du professionnel. C'est désormais un UUID technique, unique par utilisateur et sans lien avec l'ancienne valeur. La même étape introduit le champ PSISubjectNameID, qui porte l'identifiant fonctionnel PSI au format UUID pour les utilisateurs ayant activé leur identité PSI. Il est vide pour les autres.

Seconde étape (bac à sable le 31 mars 2026, production le 16 avril 2026). Lors d'une authentification par e-CPS, SubjectNameID contient désormais toujours le RPPS quand le professionnel en a un, quel que soit l'identifiant qui a servi à activer l'application. Le champ auth_level apparaît dans les jetons.

Pour votre modèle de données :

  • PSISubjectNameID ne remplace pas SubjectNameID. Le RPPS reste l'identifiant pivot, et l'ANS le décrit comme le seul identifiant pérenne dans Pro Santé Connect.
  • SubjectNameID peut être vide pour un utilisateur qui ne possède qu'une identité PSI. Décidez si votre service accepte ces profils, et gérez le cas plutôt que de le laisser lever une erreur.
  • Si votre base était indexée sur l'ancien sub, l'ANS fournit une table de correspondance entre SubjectNameID et nouveau sub : en téléchargement pour le bac à sable, sur demande au support pour la production.

Autre nouveauté, optionnelle : depuis juin 2026, la fonctionnalité CAMP permet de présélectionner l'onglet de la mire de connexion (e-CPS, carte, clé de sécurité, délégation) et de préremplir l'identifiant, via des paramètres supplémentaires de la requête d'autorisation.


Le parcours de raccordement : iSC, Datapass, bac à sable, production

Avant de toucher au code, vous devez obtenir vos identifiants auprès de l'ANS. Le parcours standard, celui de l'Espace Communautaire, passe par un bac à sable avant la production.

Les étapes du raccordement PSC

Étape Délai moyen affiché par l'ANS Résultat
1. Créer le compte iSC du responsable technique 2 semaines Compte validé sur le fournisseur d'identité de l'ANS pour les industriels
2. Déposer la demande Datapass pour l'API Pro Santé Connect 2 semaines Numéro de demande Datapass
3. Activer l'Espace Authentifié du Portail Industriels Immédiat Accès à la rubrique « Mon raccordement à Pro Santé Connect »
4. Demander le raccordement au bac à sable 2 semaines client_id et secret BAS
5. Obtenir un moyen d'identification de test Immédiat avec EDIT, 1 semaine pour une carte Identité de test e-CPS ou carte CPx de test
6. Tester en bac à sable Selon votre projet Parcours validé, service de test accessible à l'ANS
7. Demander le raccordement en production 2 semaines client_id et secret de production

À savoir avant de commencer :

  • Une demande Datapass par service. Deux services à raccorder, deux demandes. Elle se dépose depuis la fiche API Pro Santé Connect du catalogue data.gouv, avec une connexion ProConnect.
  • Deux numéros à ne pas confondre. Le formulaire de raccordement attend le numéro de demande Datapass, pas le numéro d'habilitation reçu après validation.
  • EDIT évite d'attendre une carte. L'outil EDIT génère des identités fictives utilisables avec l'application e-CPS de test. Sans lecteur de carte, c'est le chemin le plus court.
  • Le mTLS reste facultatif. L'ANS le conseille, mais dans l'Espace Communautaire vous pouvez garder l'authentification par client_secret ou passer à un certificat ORG_AUTH_CLI de l'IGC-Santé. Il devient obligatoire pour l'Espace de Confiance, l'extension qui donne accès aux API Pro Santé Connectées.

Ce que demande le dossier

Le référentiel PSC liste les pièces de la candidature :

  • un extrait Kbis ou toute pièce justifiant l'identité de l'organisme et son immatriculation ;
  • un descriptif du service : nom du traitement, finalités, types d'utilisateurs professionnels visés, modalités de contrôle d'accès ;
  • le nom public du service, son logo et une ligne de description, publiés dans la liste des services raccordés ;
  • une adresse générique du DPO et le nom de son titulaire ;
  • une adresse générique du contact opérationnel.

Le formulaire Datapass demande en plus le responsable de traitement et un responsable technique, qui recevra les accès. Les URLs de callback et de déconnexion se déclarent dans la demande de raccordement : PSC les compare ensuite à l'identique.

Ce que le référentiel exige au-delà du code

Quelques exigences se préparent en parallèle du développement :

  • un hébergement certifié HDS dès que le service traite des données de santé (EXI PSC 06), à choisir parmi les hébergeurs certifiés ;
  • le bouton Pro Santé Connect fourni par l'ANS, placé au même niveau que vos autres modes de connexion, dans le respect de la charte graphique (EXI PSC 28 à 30) ;
  • des CGU qui reprennent le paragraphe type sur Pro Santé Connect (EXI PSC 31) ;
  • le client_id et le secret conservés côté serveur, jamais sur l'appareil de l'utilisateur (EXI PSC 22) ;
  • un signalement à l'ANS sous 12 heures en cas d'incident de sécurité ou de violation de données (EXI PSC 27).

Le conseil le plus important : lancez le compte iSC et le Datapass dès le kick-off du projet. Les semaines de délai administratif courent en parallèle du développement. Si vous attendez la fin du code pour démarrer, vous ajoutez plusieurs semaines au planning pour rien.


FAQ : les questions les plus fréquentes sur Pro Santé Connect

Pro Santé Connect est-il obligatoire ?

Oui pour les services numériques en santé « sensibles », depuis le 1er janvier 2023. L'obligation vient du référentiel d'identification électronique de la PGSSI-S, rendu opposable par l'arrêté du 28 mars 2022. Sont sensibles les services qui traitent des données de santé et qui sont partagés entre plusieurs structures, intègrent un service partagé comme le DMP ou la messagerie sécurisée, offrent un accès web externe, ou dépassent 10 000 nouveaux patients ou 1 000 professionnels par an. Pour les autres, PSC est recommandé.

Quelle différence entre FranceConnect et Pro Santé Connect ?

FranceConnect authentifie les citoyens (patients). PSC authentifie les professionnels de santé (médecins, pharmaciens, infirmiers) à partir de leur carte CPS ou de leur e-CPS, et rattache l'identité à l'Annuaire Santé. Les deux utilisent le protocole OpenID Connect, mais les claims retournés sont différents : PSC fournit le numéro RPPS, le rôle professionnel et les situations d'exercice.

Comment obtenir un accès à la sandbox PSC ?

En quatre démarches : créer le compte iSC de votre responsable technique, déposer une demande Datapass pour l'API Pro Santé Connect, activer l'Espace Authentifié du Portail Industriels, puis demander le raccordement au bac à sable depuis la rubrique « Mon raccordement à Pro Santé Connect ». Vous recevez alors un client_id et un secret pour l'environnement BAS.

L'e-CPS fonctionne-t-elle avec Pro Santé Connect ?

Oui, et elle ne fonctionne qu'à travers lui. Votre application n'a rien à prévoir : la mire PSC propose l'e-CPS et la carte CPS, et le parcours OIDC est le même dans les deux cas. L'ANS compte 484 247 e-CPS actives et 39 % des authentifications PSC réalisées avec l'application (chiffres affichés en octobre 2026). C'est le moyen le plus adapté à la téléconsultation, car il ne nécessite pas de lecteur de carte.

Combien de temps prend l'habilitation PSC ?

L'ANS affiche un délai moyen de deux semaines pour chacune des quatre démarches : compte iSC, Datapass, raccordement au bac à sable, raccordement en production. Les deux premières peuvent être lancées le même jour. Le délai administratif reste le facteur limitant, d'où l'intérêt de démarrer le plus tôt possible.

Faut-il un hébergement HDS pour utiliser PSC ?

Si votre service traite des données de santé, oui : le référentiel PSC exige qu'elles soient hébergées chez un hébergeur certifié HDS (EXI PSC 06), et c'est de toute façon une obligation légale indépendante de PSC. Depuis le 16 mai 2026, un certificat HDS délivré sous l'ancien référentiel ne suffit plus : l'hébergeur doit être certifié sur le référentiel v2.

Qui a lancé Pro Santé Connect ?

Pro Santé Connect est édité et opéré par l'Agence du Numérique en Santé (ANS), l'opérateur public de la e-santé placé sous la tutelle du ministère chargé de la Santé. Le service a ouvert en 2019 et compte 756 services raccordés en production en octobre 2026. C'est un service de l'État, gratuit, et non une solution privée.

Un professionnel de santé radié peut-il encore s'authentifier via Pro Santé Connect ?

Non. Pro Santé Connect s'appuie sur l'Annuaire Santé, alimenté par le RPPS. Une radiation prononcée par l'ordre professionnel ferme la fiche RPPS et entraîne la révocation de la carte CPS et de l'e-CPS. Le professionnel ne peut donc plus obtenir de jeton PSC. Ajouter un contrôle du champ active de l'API FHIR après l'authentification n'apporte pas de garantie supplémentaire, puisque cette API interroge le même référentiel. L'Annuaire Santé reste indispensable pour un autre usage : récupérer les spécialités, savoir-faire et structures de rattachement qui alimentent vos règles d'habilitation.

Qu'est-ce que Pro Santé Identité (PSI) et qu'est-ce qui change ?

Pro Santé Identité (PSI) est le dispositif d'identité que l'ANS déploie depuis début 2026, et qui a fait évoluer les jetons PSC. Depuis le 19 mars 2026, le claim sub est un UUID technique qui ne contient plus l'identifiant national, et un champ PSISubjectNameID porte l'identifiant PSI des utilisateurs qui ont activé cette identité. Depuis le 16 avril 2026, un claim auth_level indique le niveau du moyen d'authentification. Le RPPS, lu dans SubjectNameID, reste l'identifiant sur lequel construire votre modèle de données.

Quelle est la durée de vie d'une session Pro Santé Connect ?

L'access token est valable 2 minutes et le refresh token 30 minutes. La session PSC se prolonge de 30 minutes à chaque rafraîchissement, dans la limite de 4 heures. Le référentiel demande de rafraîchir uniquement quand l'utilisateur est actif sur votre service.


Conclusion

L'intégration de Pro Santé Connect est techniquement accessible pour toute équipe familière avec OpenID Connect. Le protocole est standard, le code se résume à une Passport strategy et au parsing de quelques claims sectoriels.

Le vrai sujet n'est pas le développement, c'est la préparation : lancer les démarches tôt, connaître les bons endpoints (et surtout le host séparé pour Authorize), parser correctement les claims santé, et construire sur le RPPS plutôt que sur le sub. Une fois l'authentification en place, le travail restant se déplace vers les habilitations, où l'Annuaire Santé prend le relais.

Merci à Alexis Breithoff-Valette, qui a travaillé plusieurs années à l'ANS sur l'Annuaire Santé et la création du serveur FHIR, pour sa relecture, sa mise au point sur l'articulation entre PSC et l'Annuaire, et son signalement de la fin de vie de l'API FHIR v1.

Vous développez une application e-santé et vous avez besoin d'intégrer Pro Santé Connect ? Chez Bob le développeur, on accompagne les startups et établissements de santé, avec des fondateurs dans la e-santé depuis 2017. Parlons de votre projet.

Sources

Faits relevés le 13 octobre 2026.

Ce contenu vous a servi ? Ajoutez Bob le développeur à vos sources préférées sur Google.

E-santé

Un logiciel santé à développer ?

Applications médicales, télémédecine, medtech : on les conçoit et on les développe sur mesure, déployées chez un hébergeur certifié HDS.

  • Fondateurs dans l’e-santé depuis 2017
  • Référence AP-HP
  • Code 100 % à vous

30 min, gratuit, sans engagement.

La newsletter qu’on n’ignore pas

Abonnez-vous à notre newsletter pour recevoir nos derniers articles, retours d’expérience et conseils tech directement dans votre boîte mail.

Désinscription en un clic. Vos données restent privées.