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

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_valuesdoit valoireidas1(paseidas2)- Le numéro RPPS se trouve dans le
SubjectNameID, préfixé par8- Depuis mars 2026, le
subest 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
issdans le callback, en plus decodeetstate.
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_valuesse règle avec l'optionacrValues. La librairie ignore les options qu'elle ne connaît pas, sans erreur : une faute sur ce nom et la requête part sansacr_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 dePassportStrategy, qui fixe cette arité quelle que soit la signature devalidate. - Le
stateest stocké en session. La strategy a besoin d'un middleware de session (express-sessionou é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 :
PSISubjectNameIDne remplace pasSubjectNameID. Le RPPS reste l'identifiant pivot, et l'ANS le décrit comme le seul identifiant pérenne dans Pro Santé Connect.SubjectNameIDpeut ê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 entreSubjectNameIDet nouveausub: 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_secretou passer à un certificatORG_AUTH_CLIde 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_idet 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.
- Documentation technique de Pro Santé Connect, ANS : endpoints, flux, évolution des jetons, durées de vie, scopes
- UserInfo et exemple de jeton étendu, ANS
- Référentiel Pro Santé Connect, version 1.8.4 en vigueur, ANS
- Parcours de raccordement et déconnexion, ANS
- Référentiel d'identification électronique, acteurs personnes physiques, PGSSI-S, version 1.0
- Arrêté du 28 mars 2022 approuvant le référentiel d'identification électronique et arrêté du 4 avril 2022 encadrant Pro Santé Connect et la e-CPS
- Nomenclature des professions de santé, ANS
- Implémentations certifiées OpenID Connect, OpenID Foundation
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.