Spécifications des APIs de Mon espace santé

Spécification de l’API Appariement

Version 2.1

30/08/2023

1
 Spécifications des APIs de Mon espace santé

Historique des versions du document :

Version Date Modifications

Séparation des spécifications des API Mesures et Appariement dans deux

1 30/11/2021
documents séparés pour simplification de la lecture par les éditeurs.

Le champ iss correspond à l’OID du service tiers

1.1 24/02/2022 Respect du transport de l’INS au format CI-SIS et rappel de son caractère
facultatif

Suite aux exigences de sécurité, évolution de la cinématique de l’appariement

pour utiliser le flux Oauth2 « Authorization Code Flow with Proof Key for Code »
en lieu et place du flux Oauth2 « Client Credentials Flow ».
Ce changement a des impacts majeurs sur toute la procédure d’appariement. En
particulier l’idToken a été supprimé car l’identité de l’utilisateur pour lequel la
2.0 06/01/2023 transaction est demandée est maintenant véhiculé par l’accessToken.
Remplacement de ENS par MES (Mon Espace Santé)
L’authentification du client passe de la méthode user/password à la méthode
« Private Key JWT »
Le certificat contenant autrefois la clé publique d’identification du SNR est
remplacé par un fichier JWKS

Ajout de contenu à la rubrique « 4.5 Gestion des erreurs » concernant les statuts
2.1 30/08/2023
de comptes appairés

2
 Spécifications des APIs de Mon espace santé

Table des matières

Introduction à la documentation technique d’interopérabilité avec Mon espace santé 4
1 Introduction et objectif du document 5
2 Cinématique générale des échanges avec MES 6
2.1 Création de l’échange de données pour un utilisateur (appariement) 6
2.2 Echange de données entre le service numérique et MES 6
3 Phase d’appariement 8
3.1 Création du pairing 8
3.1.1 Introduction 8
3.1.2 Flux Oauth2 8
3.1.2.1 Authorize 9
3.1.2.2 Obtention des tokens 9
3.1.3 Eléments nécessaires 11
3.2 Paramétrage du pairing 11
3.2.1 Introduction 11
3.2.2 Appel de PATCH Pairing 12
3.2.2.1 Définition du payload de “PATCH Pairing” dans le cas d’un service-tiers sans INS : 13
3.2.2.2 Définition du payload de “PATCH Pairing” dans le cas d’un service-tiers disposant de l’INS
qualifiée pour le patient 14
3.2.3 Paramétrage du pairing via l’application MES 16
3.2.4 GET Pairing/pairing_id 16
4 Appel d’un service FHIR 18
4.1 Introduction 18
4.2 Obtention de l’accessToken 18
4.2.1 Cas Nominal 18
4.2.2 Cas de refreshToken expiré 19
4.3 Lecture des consentements par le service numérique 19
4.4 Appel du service FHIR 19
4.5 Gestion des erreurs 20
5 Gestion de versions 21
6 Sécurisation réseau 22
7 Résumé des données techniques à échanger 23

3
 Spécifications des APIs de Mon espace santé

Introduction à la documentation technique d’interopérabilité

avec Mon espace santé
La documentation technique de Mon espace santé ne s’applique qu’aux services ayant ou visant à avoir des
échanges de données avec MES.
Avant la lecture du présent document, il est conseillé de se référer au Document chapeau des APIs Mon
espace santé, qui fonctionne comme un guide d’introduction à l’interopérabilité Mon espace santé et la
documentation correspondante.
Ce document comprend :
- La liste des spécifications détaillant les échanges avec Mon espace santé ;

- Une présentation des tests d’interopérabilité requis pour compléter le référencement avec échange de
données ;

- Un glossaire des spécifications techniques ;

- Une présentation du format des profils FHIR Mon espace santé et les liens pour les trouver ;

- Un ensemble de bonnes pratiques pour préparer son interopérabilité à Mon espace santé.

Le Document chapeau des APIs Mon espace santé peut être trouvé sur le portail de référencement à
l’adresse Référencement éditeurs (monespacesante.fr).

4
 Spécifications des API de MES

1 Introduction et objectif du document

Les interactions entre les partenaires et MES s'organisent en trois phases :

- Une phase administrative d’enregistrement et de validation, non couverte par ce document, pour plus
d’informations référez-vous à la convention de référencement ;

- Une phase de setup technique, connectivité, partage de secrets, certificats, non couverte par ce
document ;

- Une phase opérationnelle d’appel des services de MES par les systèmes de prestataires qui est l’objet
des spécifications des API du store. Cette phase opérationnelle débute avec l’appariement qui est
présenté dans ce document.

5
 Spécifications des API de MES

2 Cinématique générale des échanges avec MES

L’utilisation des API de MES est conditionnée à la bonne réalisation d’une étape d’appariement initial, qui n’a
lieu qu’une fois par utilisateur, par patient et par application. Cette phase de synchronisation des comptes est
appelée appariement elle permet la création d’un ‘lien’ entre un compte du service numérique référencé (SNR)
et un compte MES, ce lien logique et technique est appelé pairing.

Pour effectuer cet appariment, l’utilisateur final devra s’authentifier à l’application MES, on suppose qu’il est déjà
authentifié au SNR.

Une fois l’appariement effectué, l’application partenaire peut appeler les APIs “métiers” de MES.

2.1 Création de l’échange de données pour un utilisateur

(appariement)

Lorsque l’utilisateur demande un appariement après s’être authentifié sur une application partenaire les deux
étapes suivantes sont réalisées :

1. Création du pairing : Une séquence d’authentification de l’utilisateur sur les serveurs de MES est
initiée à partir du SNR. Cette authentification est effectuée via le flux standard Oauth2 « Authorization
Code with PKCE ». A l’issue de l’authentification de l’utilisateur, le serveur d’autorisation crée un
access token qui matérialise l’appariement. Cet accessToken est spécifique au SNR appelant et à
l’utilisateur qui s’est authentifié. Le SNR doit stocker cet accessToken et le refreshToken qui lui est
associé

2. Paramétrage du pairing : Le SNR envoie les informations fonctionnelles du patient à MES par un
appel entre serveurs, puis l’utilisateur est débranché sur l’application MES afin de paramétrer cet
appariement : choix du titulaire (patient ayant un compte MES) et consentement sur les différentes
finalités proposées par le service. L’utilisateur ne peut choisir qu’un titulaire pour lequel il a la
dérogation. L’utilisateur est ensuite redirigé vers l’application du partenaire qui obtient le statut du
pairing ainsi que les consentements associés via un appel entre serveurs.

2.2 Echange de données entre le service numérique et MES

Une fois le pairing créé, le SNR peut à tout moment échanger des informations avec MES. Pour cela il doit
envoyer un accessToken valide. Si l’accessToken en la possession du service a expiré il doit en récupérer un
nouveau auprès de serveur d’autorisation de MES à partir du refreshToken

Lors de la demande d’un nouveau accessToken, le serveur d’autorisation retourne un nouveau accessToken
ET un nouveau refreshToken, ce dernier doit être stocké pour usage futur.

6
 Spécifications des API de MES

Le service-tiers peut appeler l’API Pairings pour obtenir les consentements de l’utilisateur. Plusieurs stratégies
sont possibles suivant l’usage du SNR :
− Obtenir les consentements avant chaque appel
− Obtenir les consentements avant un appel si le dernier rafraichissement est antérieur à x jours
− Obtenir les consentements si un appel d’une fonctionnalité métier retourne une erreur de droits d’accès.

7
 Spécifications des API de MES

3 Phase d’appariement
3.1 Création du pairing

3.1.1 Introduction
Le diagramme suivant présente les flux lors de la création du pairing

Note : Dans cette phase de création initiale l’idPairing n’est pas fourni lors de l’appel au service MES. Il est
obtenu en retour car on est dans la phase de création. Ce paramètre est utilisé dans le scénario d’un service
qui n’aurait plus de refreshToken valide (4.2.2)

3.1.2 Flux Oauth2

La création du pairing est effectuée via un flux d’authentification Oauth2 de type authorization code with PKCE
avec client privé (possédant des credentials). Le SNR doit déclencher ce flux via le endpoint standard
8
 Spécifications des API de MES

authorize en passant l’option prompt=login de manière à forcer la saisie de l’utilisateur, même s’il était déjà
connecté.

3.1.2.1 Authorize
L’url en production est : https://am.monespacesante.fr/auth/service-tiers/oauth/authorize

Sur l’environnement de tests l’url est : https://am.developer.monespacesante.fr/auth/service-

tiers/oauth/authorize

Exemple d’appel effectué par le service :

https://am.monespacesante.fr/auth/service-
tiers/oauth/authorize?client_id=123456789&response_type=code&redirect_uri=https%3
A%2F%2FredirectUrl.servicetiers.com&prompt=login&code_challenge=zszRjIZSqaOUGJa66
L9Pl4PYvpzunibm_gsIxys2oe0&code_challenge_method=S256

Le redirect_uri est l’url de redirection à laquelle le code d’autorisation sera retourné. Cette url est fournie par le
SNR lors de la phase d’administration. Lors de cette même phase, les équipes de MES fourniront le client_id
spécifique à l’application de ce SNR.

La directive « prompt=login » oblige l’utilisateur à ressaisir ses crédentials, même s’il était déjà connecté.

3.1.2.2 Obtention des tokens

Une fois le code d’autorisation récupéré, le serveur du SNR obtient un accessToken et un refreshToken via un
post sur l’url https://am.monespacesante.fr/oauth/token (ou
https://am.developer.monespacesante.fr/oauth/token sur l’environnement de qualification)

L‘authentification du serveur du SNR est effectuée suivant la méthode Private Key JWT
(https://oauth.net/private-key-jwt/). La clé publique doit être fournie à MES lors de la phase administrative de
déclaration du service sous la forme d’un fichier jwks (https://auth0.com/docs/secure/tokens/json-web-
tokens/json-web-key-sets).

Exemple de POST permettant d’obtenir les token. Cette requête sera générée par la librairie « openId »
utilisée par le service tiers.
curl -X POST \ https://am.monespacesante.fr/auth/service-tiers/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code&code=eW6xVq-F9Dn9YoBu4iYwvFWI4nnxSzsJnxQLzJzOgYA&cli-
ent_id=22123456789&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-
type%3Ajwt-bearer&client_assertion= ASSERTION_JWT_TOKEN &redirect_uri=https://redirectUrl.ser-
vicetiers.com&code_verifier=ZW9udDRiZm83RnZzNmxnMmtXdVY1cGh3bHNpYzlLMnY'

9
 Spécifications des API de MES

Le ASSERTION_JWT_TOKEN est le token créé et signé par le service tiers. Dans la pratique ce token est
générée par la librairie OpenId utilisée par l’appelant. Client_assertion_type est une constante : « client_as-
sertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer”

Ci-dessous un exemple de token

En-tête du token
{
"alg": "RS256",
"typ": "JWT",
"kid": "9F:DA:A5:69:F2:93:2C:DE:EB:70:66:A0:E5:D5:7E:F2:72:BD:C3:F3"
}
Payload du token
{
"sub": "22123456789",
"iss": "22123456789",
"aud" : "https://am.developer.monespacesante.fr:443/auth/service-tiers/oauth/token",
"jti" : "123456789",
"exp" : 1516249022,
"iat": 1516239022
}

Avec :
• kid : le key ID qui correspond à la valeur fournie dans le fichier jwks de la clé qui a servi à la signature.
• Client_assertion_type : valeur fixe indiquant une authentification du client par JWT
• Client_assertion : JWT signé par le client. (https://openid.net/specs/openid-connect-core-1_0.html#Clien-
tAuthentication )
• Code_verifier : est une chaîne aléatoire utilisant les caractères A-Z, a-z, 0-9 et les caractères de ponc-
tuation (-._~) d'une longueur entre 43 et 128 caractères.
• Sub : le ClientID
• Iss : le ClientID
• Jti : un numéro unique à chaque appel
• Exp et iat : sont les timestamp (standard JWT)

Documentation de référence :
• https://www.rfc-editor.org/rfc/rfc7523
• https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication
• https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets

Le refreshToken est fourni de manière à permettre au SNR d’obtenir un nouvel accessToken sans
l’intervention de l’utilisateur. Il expire au bout de 1 an sans utilisation.

L’accessToken aura quant à lui une durée limitée de 5 minutes.

Les éditeurs doivent mettre en place les dispositifs de sécurité nécessaires pour garantir la sureté, la
disponibilité et la confidentialité (ex. chiffrement) afin d'assurer la sécurité des informations (de MES) des
usagers

Comme décrit plus haut, l’obtention des tokens nécessite l’authentification du SNR, de ce fait les refreshToken
ne sont pas utilisables par une personne qui ne possède pas les informations permettant d’authentifier le SNR
10
 Spécifications des API de MES

(la clé privée).

Il est à noter que ni l’access token ni le refresh token ne doivent être exposés au navigateur de la webapp du
SNR. https://www.rfc-editor.org/rfc/rfc6749#section-2.1 client type “confidential”.

L’accessToken permet l’accès aux API MES. Il doit être envoyé dans l’en-tête : “Authorization: Bearer
<Token>”. Cet accessToken contient le champ « pid » pour « pairingid » qui est la matérialisation de
l’appariement entre un patient du service et le même patient coté MES, appelé « titulaire ». Ces informations
sont immutables c’est-à-dire qu’une fois que l’appariement est effectué le patient coté ST et le titulaire ne
peuvent pas être modifiés.

3.1.3 Eléments nécessaires

Eléments à fournir par le SNR afin de paramétrer le serveur d’autorisation de MES :

- L’url de callback
- Le fichier jwks contenant la clé publique permettant d’authentifier le serveur du service.

En retour les équipes de MES fournissent :

- Le clientId associé à l’application du service

3.2 Paramétrage du pairing

3.2.1 Introduction

Le paramétrage du pairing est effectué via l’utilisation du endpoint /Pairing coté SNR et par l’utilisation de
l’application MES par l’utilisateur. Le même endpoint /Pairing permet avec l’action GET d’obtenir les informations
sur un pairing.

Le schéma suivant résume les interactions.

11
 Spécifications des API de MES

3.2.2 Appel de PATCH Pairing

Cette API doit être appelée juste après le flux d’authentification Oauth2, elle permet de fournir à MES les
informations descriptives du patient tel qu’il est connu par le SNR. En particulier le servie tiers fournira l’Identifiant
de patient externe (IDPE).

Définition de l’identifiant Patient Externe (idpe) :

- Il s’agit d’un identifiant qui identifie de manière unique (au sein du domaine d’identification du service
partenaire) le patient pour qui on souhaite échanger des informations avec l’ENS.

- Cet identifiant est un objet décomposé en deux champs : assign_auth et value.

- Le champ assign_auth de l’IdentifiantPatientExterne, est une extension de l’OID racine du service. Sa

12
 Spécifications des API de MES

définition est sous la responsabilité du service numérique

- Le champ value de l’identifiantPatientExterne ne doit pas être un identifiant déjà utilisé dans le système
du partenaire pour identifier ce patient, pour des raisons de sécurité. Cela peut néanmoins par
exemple être un hash d’un identifiant déjà utilisé.

L‘appel de cette API, comme l'appel des APIs FHIR, nécessite l’envoi de l’access token dans le header
« Authorization ».

L’appel doit comporter le pairing_id dans l’url : PATCH /Pairing/<pairingID>

Le pairingID doit être le même que le « pid » contenu dans l’access token. Si ce n’est pas le cas MES rejettera
la requête avec un code 403.

Si le pairing n’est pas trouvé pour cet utilisateur, le serveur MES retourne une valeur 404 (not found). Ce dernier
cas ne doit pas arriver en utilisation normale.

3.2.2.1 Définition du payload de “PATCH Pairing” dans le cas d’un service-tiers sans INS :

Attention : Lors d’un appel le service-tiers doit remplir obligatoirement l’idpe et le given_name ainsi qu’une
des combinaisons suivantes :
- Soit un login ;
- Soit un email ;
- Soit un given_name et un family_name ;
- Soit un first_name et un Last_name ;
- Soit un First_name et un Family_name ;

Champ Niv Card Type JSON Commentaire

user 1 0..1 Objet

family_name 2 0..1 String (Trait INS) Nom de naissance
given_name 2 0..1 String (Trait INS) Liste des prénoms de naissance
(séparateurs espace)
patient 1 1 Objet
idpe 2 1 String Identifiant du patient coté service. C’est la seule
valeur qui sera autorisée dans les champs
« subject » des échanges FHIR.
assign_auth 3 1 String ID de l’autorité d’affectation de l’IDPE
value 3 1 String Valeur de l’IDPE
family_name 2 0..1 String (Trait INS) Nom de naissance – Voir Attention plus
haut
family_name_usual 2 0..1 String (Trait RNIV) Nom utilisé – Voir Attention plus haut
given_name 2 1 String (Trait INS) Liste des prénoms de naissance
(séparateurs espace) – Voir Attention plus haut

13
 Spécifications des API de MES

given_name_usual 2 0..1 String (Trait RNIV) Prénom utilisé – Voir Attention plus
haut
first_name 2 0..1 String (Trait RNIV) Premier prénom – Voir Attention plus
haut
email 2 0..1 String Email du patient qu’il utilise pour se connecter au
SNR – Voir Attention plus haut
login 2 0..1 String Identifiant que le patient utilise pour se connecter au
SNR – Voir Attention plus haut
gender 2 0..1 String (Trait INS) Sexe. Valeurs possibles : « M » ou « F »
birth_date 2 0..1 Date (Trait INS) Date de naissance (AAAAMMJJ, avec
règles RNIV pour dates exceptionnelles)
birth_place 2 0..1 String (Trait INS) Lieu de naissance Code Officiel
Géographique (COG) INSEE de la commune ou du
pays du lieu de naissance

3.2.2.2 Définition du payload de “PATCH Pairing” dans le cas d’un service-tiers disposant de l’INS
qualifiée pour le patient

Lors d’un appel le service-tiers doit remplir obligatoirement l’idpe du patient :

Champ Niv Card Type JSON Commentaire

user 1 0..1 Objet
family_name 2 0..1 String (Trait INS) Nom de naissance
given_name 2 0..1 String (Trait INS) Liste des prénoms de naissance
(séparateurs espace)
patient 1 1 Objet
Idpe 2 1 Objet Identifiant du patient coté service. C’est la seule
valeur qui sera autorisée dans les champs
« subject » des échanges FHIR.
assign_auth 3 1 String ID de l’autorité d’affectation de l’IDPE
value 3 1 String Valeur de l’IDPE
family_name_usual 2 0..1 String (Trait RNIV) Nom utilisé
given_name_usual 2 0..1 String (Trait RNIV) Prénom utilisé
first_name 2 0..1 String (Trait RNIV) Premier prénom
family_name 2 1 String Nom de naissance
given_name 2 1 String Liste des prénoms de naissance (séparateurs
espace), seul le premier prénom de la liste est
obligatoire
gender 2 1 String Sexe. Valeurs possibles : « M » ou « F »
birth_date 2 1 Date Date de naissance (AAAAMMJJ, avec règles RNIV
pour dates exceptionnelles1)

1
https://solidarites-sante.gouv.fr/soins-et-maladies/qualite-des-soins-et-pratiques/securite/securite-des-soins-securite-des-
patients/article/identitovigilance
14
 Spécifications des API de MES

birth_place 2 0..1 String Lieu de naissance Code Officiel Géographique

(COG) INSEE de la commune ou du pays du lieu de
naissance
ins 2 1 Objet Matricule INS du patient
assign_auth 3 1 String ID de l’autorité d’affectation de l’INS
value 3 1 String Valeur de l’INS

Le matricule INS ne doit pas être véhiculé seul, il doit être accompagné des traits d’identité des bases
nationales de référence : nom de naissance, prénom(s) de naissance, date de naissance, sexe, lieu de
naissance dans le respect du référentiel INS.

Exemple de requête avec INS :

{
user : {
family_name: “dupont”,
given_name: “alain”
},
patient : {
idpe : {
assign_auth : “OID du ST”,
value : “xxxxxx”
}
,
family_name : “dutronc”,
given_name : “alexis marc”,
gender : “M”,
birth_date : “19600530”,
birth_place : “88154”,
ins: {
assign_auth : “1.2.250.1.213.1.4.8”, // pour la prod. Pour le test c’est 4.10
value : “178103178745414”
}
}
}

Réponses :

- En cas de succès le code “204” (no content) est retourné. Le lien vers la ressource est retourné dans
l’en-tête http “Location”. Exemple :

Location: /Pairing/255fdjkldf5dfs54df

- Dans le cas où l’utilisateur a déjà un appariement pour le patient (idpe) fourni (et bien sûr pour le service
demandant), le code “400” est retourné. Il peut être judicieux d’inviter l’utilisateur à se rendre sur MES
afin de vérifier et potentiellement modifier les pairing qu’il possède.

{
"error_type": "existing_pairing",

15
 Spécifications des API de MES

"error_description": "You already own a pairing for idpe=5454845"

}

3.2.3 Paramétrage du pairing via l’application MES

Une fois le PATCH Pairing réalisé, le SNR doit rediriger l’utilisateur vers l’application MES.

Cette cinématique a deux redirections :

- La redirection vers MES depuis le site du partenaire, juste après l’appel à l’API PATCH d’appariement

- Le retour vers le site du partenaire depuis MES après validation de l’appariement

Ces redirections sont effectuées sous la forme d’url fixes définies. Aucun paramètre n’est passé dans les appels
car suite à la phase d’authentification Oauth2 le système du SNR et MES sont déjà synchronisés.

URL de redirection vers MES :https://www.monespacesante.com/parametrage-appariement

Exemple d’URL de retour vers le SNR, spécifique à chaque SNR, et fournie lors de la phase d’enregistrement
du SNR.
https://www.medicaments.com/finappariement

3.2.4 GET Pairing/pairing_id

Une fois le pairing réalisé et à tout moment par la suite, le service peut obtenir l’état du pairing et la liste des
consentements pour l’appariement concerné via le endpoint /Pairing

L‘appel de cette API, comme l’appel des APIs FHIR, nécessite l’envoi de l’access token dans le header
« Authorization ».

L’appel doit comporter le pairing_id dans l’url : GET /Pairing/<pairingID>

Le pairingID doit être le même que le « pid » contenu dans l’access token. Si ce n’est pas le cas MES rejettera
la requête avec un code 403.

Si le pairing n’est pas trouvé pour cet utilisateur, le serveur MES retourne une valeur 404 (not found). Ce dernier
cas ne doit pas arriver en utilisation normale.

Exemple : GET Pairing/123812

Définition du corps de la réponse du GET :

Champ Niv Card Type JSON Commentaire

status 1 1 String Etat du pairing. Les valeurs actuelles sont :

16
 Spécifications des API de MES

- « N », en cours de création (nex)

- « A », Actif
- « D », Delete
purposes 1 1 Array Tableaux des finalités avec leur scopes associés.
Les pairings dans l’état « N » ou « D » n’ont pas de finalités
associées (liste vide)
purpose_id 2 1 String Id de la finalité (partagé avec le service lors de la phase de
référencement)
scopes 3 0..1 Array Contient la liste des scopes en s’inspirant de la syntaxe de
“openid_heart_fhir”.

https://openid.net/specs/openid-heart-fhir-oauth2-
1_0.html#rfc.section.2

Note 1 : Les spécifications sur l’accès précisent uniquement les notions « read » et « write ». Dans le cadre
de MES ces droits sont trop génériques et nous utilisons les access suivants : « create », « read », « update »,
« delete » (https://openid.net/specs/openid-heart-fhir-oauth2-1_0.html#Access)

Note 2 : Les spécifications “openid_heart_fhir” ont une granularité des scopes uniquement au niveau de la
ressource par exemple “Observation”. Pour les besoins de MES cette nomenclature est étendue pour avoir une
granularité plus fine adaptée à chaque ressource.

La liste des scopes est entièrement définie pour chaque ressource dans la spécification qui lui correspond.

17
 Spécifications des API de MES

4 Appel d’un service FHIR

4.1 Introduction

Ce chapitre présente les généralités pour l’appel d’un service FHIR de MES par un service numérique une fois
la phase de synchronisation des comptes (pairing) effectuée. Le détail des payloads envoyés dépend de la
ressource FHIR demandée et est spécifiée dans des documents séparés

Le diagramme suivant reprend les divers échanges de cette phase

4.2 Obtention de l’accessToken

4.2.1 Cas Nominal

L’appel des services FHIR de MES est sécurisé par un accessToken. Cet accessToken a été obtenu lors de la
phase initiale de la synchronisation (le pairing). Par la suite lorsque l’accessToken a expiré, le SNR peut
obtenir un nouveau AccessToken auprès de notre Authorization server en fournissant le refreshToken.

Url pour le POST : https://am.monespacesante.fr/oauth/token

Exemple d’appel pour obtenir de nouveaux token. Le grant_type doit valoir ‘refresh_token’. Le refresh token
est fourni dans la variable refresh_token. Les autres paramètres sont similaires à l’appel du endpoint /token
défini dans le flus Oauth2 (3.1.2.2)
18
 Spécifications des API de MES

curl --verbose -X POST \

https://am.monespacesante.fr/auth/service-tiers/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=refresh_token&refresh_token=<Mettre ici le refresh Token>
&client_id=22123456789&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-
assertion-type%3Ajwt-bearer&client_assertion=<AssertionJWT> &redirect_uri=<Url de
redirection>'

Attention, un nouveau refreshToken sera retourné et doit être utilisé pour le prochain rafraîchissement.

4.2.2 Cas de refreshToken expiré

Dans le cas où le refreshToken est lui-même expiré, le SNR doit déclencher un flux Oauth2 similaire à celui
effectué lors de la synchronisation initiale avec en paramètre de la méthode /authorize le paramètre
pid=<pairingID>.
Cela implique :
− Que le SNR a enregistré le pairingID associé à cet appariement lors de la phase initiale d’appariement
(à partir du claim pid de l’accessToken)
− Que l’utilisateur soit connecté au SNR.

Le serveur MES vérifiera que le pairingID demandé a bien été créé par l’utilisateur qui se sera authentifié et
est encore valide.

4.3 Lecture des consentements par le service numérique

Avant de faire un appel FHIR il est possible d’obtenir les consentements donnés par l’utilisateur en appelant
l’api /Pairing/<pairingId> comme détaillé au chapitre 3.2.4

4.4 Appel du service FHIR

Le service FHIR est appelé sur l’url

https://fhir.monespacesante.fr/gateway/v1/fhir/<Ressource>

En dehors du payload fonctionnel les deux headers suivants sont obligatoires :

Authorization : Bearer <AccessToken>
Purpose_id : <code de la finalité>

Note : un contrôle de cohérence est effectué entre les champs FHIR qui font référence au patient (subject) et
le patient qui a été déclaré lors de l’appariement (idpe).

19
 Spécifications des API de MES

4.5 Gestion des erreurs

En cas d’erreur de traitement fonctionnel lors de l’appel d’une API (et uniquement erreur de traitement),
le service retourne un objet de type “OperationOutcome” et un code de type “4XX”. Cela ne s’applique pas pour
la partie appariement (hors FHIR).
A contrario, des erreurs de type “401” (unauthorized), “404” (forbidden) ou “5XX” qui ne sont pas liées à une
erreur de traitement et ne renvoient pas de “body”.

Dans le cas où un usager a 2 comptes SNR et tente d’appairer les deux à son compte MES, seul le premier
compte appairé sera relié à Mon espace santé.
L’usager tentant de connecter son second compte recevrait un message d'erreur le prévenant qu’il a déjà un
appariement actif sur la solution. Dans ce cas l'IDPE (identifiant relié à la solution) n’a pas priorité sur l'idEns
(identifant MES).
Un seul appariement par idEns et par OID.

Dans le cas où un usager retire ses consentements et par conséquent annule le pairing, l’éditeur recevra
un code erreur 401 en cas d’appel à MES. Dns ce cas il peut lancer un appel pour checker les consentements
et recevra le statut « Désapairé » qui confirme la résiliation de l’appariement par l’usager.
Des notifications en cas de modifications des consentements sont en cours de développement mais leur mise
en production n’est pas encore planifiée.

Dans le cas où un Service Numérique Référencé souhaite mettre fin au pairing d’un usager, il peut
s’adresser au support éditeur à l’adresse : [email protected].

20
 Spécifications des API de MES

5 Gestion de versions
Les APIs sont versionnées de manière à laisser la latitude aux utilisateurs afin de choisir le meilleur
moment pour monter de version.

La version fait partie de l’url d’appel des APIs et est obligatoire par exemple :
“https://fhir.monespacesante.fr/gateway/v1/fhir/Observation”.

Le système MES n’accepte que la version actuelle et la version n-1. En cas de problèmes de sécurité une
version peut être rendue obsolète par décision de Mon espace santé.

21
 Spécifications des API de MES

6 Sécurisation réseau
Les échanges avec le serveur d’autorisation de MES se font sur TLS1.2 avec certificat serveur sur le domaine
am.monespacesante.fr. Le certificat serveur est un certificat RGS comme pour tous les sous-domaines de
monespacesante.fr

Les accès à l’URL d’appel de l’API fhir.monespacesante.fr sont protégés par une whitelist dans
l’environnement de qualification et dans l’environnement de production.

22
 Spécifications des API de MES

7 Résumé des données techniques à échanger

Quoi Fournisseur Quand Commentaire
Fichier au format JWKS SNR A l’enregistrement du
contenant la clé publique SNR et quand la clé
pour les credentials change. Il est possible
OAuth2 d’avoir plusieurs clés
dans le même fichier
Url de retour Oauth2 SNR A l’enregistrement du
SNR et si jamais elle
change
Url de retour du SNR A l’enregistrement du
paramétrage du pairing SNR et si jamais elle
dans MES change
OID SNR Lors de l’enrôlement du
SNR
ClientId du SNR CNAM Lors du paramétrage du
SNR dans nos systèmes

Récapitulatif du format jwks

• keys : les clés définies
• kty : RSA : l’algorithme à utiliser
• x5c : la chaine de certificat, le premier est celui qui contient la clé publique
• n et e : la clé publique
• alg : RS256 : algorithme de signature
• kid : id de la clé. Cet id sert à « mapper » la clé avec celui qui est fourni dans le header du jeton qui
constitue l’attestation
• use : sig pour signature

Exemple de fichier jwks :

{
"keys": [
{
"kty": "RSA",
"x5c":
["MIID8zCCAtugAwIBAgIUG0v/L1pJC0K7ASF91mNjm/a7aEgwDQYJKoZIhvcNAQELBQAwgYgx
CzAJBgNVBAYTAkZSMRMwEQYDVQQIDApTb21lLVN0YXRlMRwwGgYDVQQKDBNTVCBkZSB0ZXN0IH
BvdXIgTUVTMSEwHwYDVQQDDBhmaGlyLm1vbnN0Lm1vbmRvbWFpbmUuZnIxIzAhBgkqhkiG9w0B
CQEWFGFsYWluLmZhdXJlQG9jdG8uY29tMB4XDTIzMDExMDEzNTE0MloXDTI0MDExMDEzNTE0Ml
owgYgxCzAJBgNVBAYTAkZSMRMwEQYDVQQIDApTb21lLVN0YXRlMRwwGgYDVQQKDBNTVCBkZSB0
ZXN0IHBvdXIgTUVTMSEwHwYDVQQDDBhmaGlyLm1vbnN0Lm1vbmRvbWFpbmUuZnIxIzAhBgkqhk
iG9w0BCQEWFGFsYWluLmZhdXJlQG9jdG8uY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB
CgKCAQEAxaNJXuqGwohjUpAlrGPP82oZSiucL5Xe0GNBKWCnJOuSQA/FXlRB8lFv8e6Z/x2sYM
gmlDQ0Gl9DGFpnkEJ290nMQnXPiOqnfj6WcUHnKZmtOwsRcneK8Hgf51jWl1CtzM8hyyqoDlpe

23
 Spécifications des API de MES

tXBpMJEmNst0T4ilvQE/92+WzPlpNSlLS9LSz1bMCgv3vR4aZ2Uq8Pk7GS7W7NzgCmYX+wmK0V
908RsCSQ4V9eKFFugM6zOlpydNNn5BK8Y/b1+6zWhWiU4wz2e5yvyI03QC1kNu4AhXhp92Dlw9
RdwPhLSzuX7oV5vZXqrGHakg3EQ5XUyD/wYKWcMXRZbMBseEL6LQIDAQABo1MwUTAdBgNVHQ4E
FgQUn9qlafKTLN7rcGag5dV8nK9w/MwHwYDVR0jBBgwFoAUn9qlafKTLN7rcGag5dV8nK9w/Mw
DwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAtyJgsvJYalBwhtiwIkQtTXiJ8r
AKIhNqM/nZGanjdkUomazU/gNbNNRkJnsKCNqC1Ev7KLNRb3neb3Dc98XEGVa/GkEavUBs4C41
ZqCD77Cyj7vvlgTt2M4bkrbiKMt028THzVqhMUVARgH7jWtB3xYheZYeAYMidrflfOfdB9GZDl
Rl9jVOow0WgHJYKuHfmMZAc67W2W9eQRMW3ug9Zcym4C3W/5vFcXJdn8XKvNimAL1O1IpODr8L
YNMm7AJICAm5NsAygGJUwfc/RilVRLHAqMbFwkTYc1NlKxvtbDiBw7VrV5eylWxK6Z9iDoLbwF
YEmiYFb3/Hm2mTA=="],
"n":
"xaNJXuqGwohjUpAlrGPP82oZSiucL5Xe0GNBKWCnJOuSQA_FXlRB8lFv8e6Z_x2sYMgmlDQ0G
l9DGFpnkEJ290nMQnXPiOqnfj6WcUHnKZmtOwsRcneK8Hgf51jWl1CtzM8hyyqoDlpetXBpMJE
mNst0T4ilvQE_92-Wz-PlpNSlLS9LSz1bMCgv3vR4aZ2Uq8Pk7GS7W7NzgCmYX-
wmK0V908RsCSQ4V9eKFFugM6zOlpydNNn5BK8Y_b1-
6zWhWiU4wz2e5yvyI03QC1kNu4AhXhp92Dlw9RdwPhLSzuX7oV5vZXqrGHakg3EQ-
5XUyD_wYKWcMXRZbMBseEL6LQ",
"e": "AQAB",
"alg": "RS256",
"kid": "9F:DA:A5:69:F2:93:2C:DE:EB:70:66:A0:E5:D5:7E:F2:72:BD:C3:F3",
"use": "sig"
}
]
}

24