API Authentic¶
Notes de version¶
Version |
Auteur |
Remarque |
0.1 |
bdauvergne |
Première version, manque la définition du format pour la description des comptes et des erreurs |
15122016 |
0.2 |
mates |
Ajout paramètres pour l'envoi de mail à la création |
08032017 |
0.3 |
bdauvergne |
Mise à jour pour conformité avec la liste des attributs du compte |
21032017 |
0.4 |
bdauvergne, mates |
URLs, ex modified__gte, envoi email à la création, forcer changement de mot de passe, test existence en masse |
26062017 |
0.5 |
jkouka, mates |
Correction valeurs attributs gender, utilisation des alias d'attributs, ajouts appels suppression fédération FC et envvoi jeton réinit mot de passe |
10072017 |
0.6 |
bdauvergne, mates |
Ajout du service de modification d'une adresse de messagerie |
31082017 |
0.7 |
mates |
Ajout des attributs FranceConnect |
01092017 |
0.8 |
mates |
Contrôle sur les attributs |
10102017 |
0.9 |
mates |
Précisions sur la pagination |
16022018 |
0.10 |
bdauvergne |
Première ébauche API validation des comptes |
05032018 |
0.11 |
bdauvergne, mates |
Version initiale API validation des comptes |
14032018 |
0.12 |
mates |
Corrections mineures sur API validation des comptes |
23042018 |
0.13 |
mates |
Corrections sur les urls, corrections mineures diverses |
24042018 |
0.14 |
bdauvergne |
Ajout code schema-error pour API de validation des identités |
25042018 |
0.15 |
bdauvergne |
Ajout paramètre page pour le code d'erreur justificatifs-bad-format pour l'API de validation des identités |
25042018 |
0.16 |
bdauvergne |
Ajout remarque sur le WS de test des comptes en masse |
02072018 |
0.17 |
mates |
Publication sur projet Authentic |
30072018 |
Disclaimer¶
Il s'agit d'un travail en cours. Certaines des fonctionnalités présentées peuvent ne pas être encore disponibles dans authentic mais uniquement dans authentic2-cut.
Aperçu¶
Cette API offre la possibilité de créer, lire, modifier et rechercher et supprimer (CRUD) des utilisateurs.
Transport¶
HTTP obligatoire
Style de l'interface¶
REST/JSON
Authentification¶
L'authentification se fait via un login et un mot de passe en utilisant le mode d'authentification HTTP Basic.
Contrôle d'accès¶
En utilisant la fonctionnalité des rôles affectés aux utilisateurs techniques il est possible d'autoriser ou non les différentes actions: créer, modifier, rechercher, supprimer.
Contrôle sur les attributs¶
La valeur d'un champs de téléphone peut débuter par un '+'. Elle ne doit ensuite contenir que des chiffres, maximum 20.
Les champs nom et prénoms de naissance sont limités à 64 caractères.
Les autres champs sont limités à 256 caractères.
Liste/recherche un compte¶
URL |
Méthode |
Contenu |
Paramètres |
/api/users/ |
GET |
document JSON |
voir plus loin |
Paramètres¶
Nom |
Sémantique |
Valeurs permises |
Exemple |
ordering |
Permet de passer le nom d'un champ par lequel les réponses seront ordonnées, préfixé par - l'ordre est inversé, ex.: ordering=last_name |
[-]date_joined , [-]modified , [-]first_name , [-]last_name |
first_name |
recherche exacte sur le prénom pour une valeur exacte |
|
|
first_name__iexact |
recherche exacte sur le prénom pour une valeur exacte en ignorant la casse |
|
|
first_name__icontains |
recherche exacte sur le prénom pour une sous chaîne en ignorant la casse |
|
|
first_name__gte |
recherche sur le prénom supérieure ou égale à la valeur |
|
|
first_name__lte |
recherche sur le prénom inférieure ou égale à la valeur |
|
|
first_name__gt |
recherche sur le prénom supérieure à la valeur |
|
|
first_name__lt |
recherche sur le prénom inférieure à la valeur |
|
|
last_name + __iexact , __icontains , __gte , __lte , __gt , __lt |
idem que pour le prénom mais avec le nom |
|
|
modified__gte |
recherche sur la date de dernière modification supérieure ou égale à la valeur |
date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS |
curl -X GET -u partenaire:geronimo https://connexion-grandlyon.dev.entrouvert.org/api/users/?modified__gte=2017-03-28T00:00:00 |
modified__lte |
recherche sur la date de dernière modification inférieure ou égale à la valeur |
date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS |
|
modified__gt |
recherche sur la date de dernière modification supérieure à la valeur |
date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS |
|
modified__lt |
recherche sur la date de dernière modification inférieure à la valeur |
date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS |
|
email |
recherche sur le courriel exact |
|
|
email__iexact |
recherche sur le courriel exact en ignorant la casse |
|
|
Format retour¶
Le document retour est un objet/dictionnaire JSON, les résultats sont toujours paginés, chaque page a une taille de 100, le lien vers la page suivante est dans la propriété next
et celui vers la page précédente
dans la propriété previous
. La propriété results
contient la liste des résultats.
Les résultats contiennent les propriétés suivantes:
Propriété |
Description |
Format |
sub |
identifiant |
chaîne hexadécimal |
first_name |
prénom |
chaîne quelconque |
given_name |
idem (alias) |
idem |
last_name |
nom |
chaîne quelconque |
family_name |
idem (alias) |
idem |
email |
courriel |
courriel |
gender |
genre de la personne |
male ou female |
birthdate |
date de naissance |
format ISO8601: YYYY-MM-DD |
birthplace |
lieu de naissance |
chaîne quelconque |
birthplace_insee |
code INSEE du lieu de naissance |
code INSEE (https://www.insee.fr/fr/information/2114819) |
birthcountry |
pays de naissance |
chaîne quelconque |
birthcountry_insee |
code INSEE du pays de naissance |
code INSEE (https://www.insee.fr/fr/information/2028273) |
birthdepartment |
nom du département de naissance |
chaîne quelconque |
preferred_givenname |
prénom préféré |
chaîne quelconque |
preferred_username |
nom préféré |
chaîne quelconque |
comment |
commentaire |
chaîne quelconque |
title |
civilité |
"Monsieur" ou "Madame" |
address_number |
adresse: numéro de voie |
chaîne quelconque |
address_street |
adresse: type et nom de la voie |
chaîne quelconque |
address_complement |
adresse: complément d'adresse |
chaîne quelconque |
address_zipcode |
adresse: code postal |
chaîne quelconque |
address_city |
adresse: nom de la ville |
chaîne quelconque |
address_country |
adresse: pays |
chaîne quelconque |
address_fc |
attribut address fournie par FranceConnect |
Object JSON tel que défini dans les spécifications OpenIDConnect 1.0 |
home_phone |
téléphone fixe personnel |
Peut commencer par un '+'. Ne contient ensuite que des chiffres, maximum 20. |
home_mobile_phone |
téléphone fixe personnel |
Peut commencer par un '+'. Ne contient ensuite que des chiffres, maximum 20. |
professional_phone |
téléphone fixe professionnel |
Peut commencer par un '+'. Ne contient ensuite que des chiffres, maximum 20. |
professional_mobile_phone |
téléphone fixe professionnel |
Peut commencer par un '+'. Ne contient ensuite que des chiffres, maximum 20. |
phone_number_fc |
attribut phone fourni par FranceConnect |
chaîne quelconque |
modified |
date dernière mofification |
date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS |
validated |
statut de validation du compte |
booléen |
validation_date |
date de validation du compte |
format ISO8601: YYYY-MM-DD |
validation_context |
contexte de validation |
énumération: "FC" ou "online" ou "office" |
Exemple cas-passant¶
GET /api/users/ HTTP/1.1
Authorization: Basic xxx
200 Ok
Content-Type: application/json
Content-Length: xxxx
{
"next": "https://cresson.entrouvert.org/api/users/?cursor=XYZ",
"previous": null,
"results": [
{
"address_city": "",
"address_complement": "",
"address_country": "",
"address_fc": {
"country": "France",
"formatted": "26 rue Desaix, 75015 Paris",
"locality": "Paris",
"postal_code": "75015",
"region": "Ile-de-France",
"street_address": "26 rue Desaix"
},
"address_number": "",
"address_street": "",
"address_zipcode": "",
"birthcountry": "FRANCE",
"birthcountry_insee": "99100",
"birthdate": "1981-06-23",
"birthdepartment": "",
"birthplace": "GIF-SUR-YVETTE",
"birthplace_insee": "91272",
"comment": null,
"creation_domain": null,
"creation_mode": null,
"creation_partner": null,
"date_joined": "2017-07-25T08:41:40.998793Z",
"email": "eric.mercier@france.fr",
"email_verified": true,
"family_name": "Mercier",
"first_name": "Eric",
"gender": "male",
"given_name": "Eric",
"home_mobile_phone": "",
"home_phone": "",
"is_active": true,
"last_name": "Mercier",
"modified": "2017-08-31T15:16:29.690864Z",
"phone_number_fc": null,
"preferred_givenname": "",
"preferred_username": null,
"professional_mobile_phone": "",
"professional_phone": "",
"sub": "YTIBAQB9-fZcwZKt7k28P_towGlszsW0uDvxq5hd_zQOJhGBJ1qP3FYajF-JUY6ug_Ekw8k",
"title": "Monsieur",
"validated": "True",
"validation_context": "FC",
"validation_date": "2017-08-31"
},
...
]
}
Cas non-passant¶
Code |
Signification |
Contenu |
400 |
Le format de la requête est invalide (paramètre interdit ou avec une valeur invalide) |
Un document JSON décrivant les erreurs rencontrées |
401 |
L'authentification a échouée |
|
403 |
Permission non accordée d'effectuer l'action |
|
Pagination des résultats¶
La réponse d'un cas passant contient au maximum 100 comptes. Si le résultat est supérieur à 100 comptes, le résultat se découpe en plusieurs pages et la réponse à la requête initiale ne contient que les 100 premiers comptes de la liste. Il faut ensuite parcourir les pages suivantes en interrogeant l'url spécifiée dans le champs next
de la réponse et cela jusqu'à ce que le champs next
soit à null
.
Par exemple :
GET /api/users/ HTTP/1.1
Authorization: Basic xxx
200 Ok
Content-Type: application/json
Content-Length: xxxx
{
"next": "https://moncompte.grandlyon.com/api/users/?cursor=XYZ",
"previous": null,
"results": [
{
...
Le champs next
indique qu'il y a une autre page de résultat que l'on obtient par la requête :
GET /api/users/?cursor=XYZ HTTP/1.1
Authorization: Basic xxx
200 Ok
Content-Type: application/json
Content-Length: xxxx
{
"next": null,
"previous": "https://moncompte.grandlyon.com/api/users/?cursor=ABC",
"results": [
{
...
Création d'un compte¶
URL |
Méthode |
Contenu |
Paramètres |
/api/users/ |
POST |
document JSON décrivant le compte à créer (à spécifier) |
non |
Format entrée¶
Le document en entrée est un object/dictionnaire JSON avec les propriétés suivantes:
Propriété |
Description |
Valeur requise |
Valeur permise |
first_name |
prénom |
oui |
chaîne quelconque |
last_name |
nom |
oui |
chaîne quelconque |
email |
courriel |
non |
courriel |
gender |
genre de la personne |
non |
entier: 1 = homme, 2 = femme |
birthdate |
date de naissance |
non |
format ISO8601: YYYY-MM-DD |
birthplace |
lieu de naissance |
non |
chaîne quelconque |
birthplace_insee |
code INSEE du lieu de naissance |
non |
code INSEE (https://www.insee.fr/fr/information/2114819) |
birthcountry |
pays de naissance |
non |
chaîne quelconque |
birthcountry_insee |
code INSEE du pays de naissance |
non |
code INSEE (https://www.insee.fr/fr/information/2028273) |
birthdepartment |
nom du département de naissance |
non |
chaîne quelconque |
preferred_givenname |
prénom préféré |
non |
chaîne quelconque |
preferred_username |
nom préféré |
non |
chaîne quelconque |
comment |
commentaire |
non |
chaîne quelconque |
title |
civilité |
non |
"Monsieur" ou "Madame" |
address_number |
adresse: numéro de voie |
non |
chaîne quelconque |
address_street |
adresse: type et nom de la voie |
non |
chaîne quelconque |
address_complement |
adresse: complément d'adresse |
non |
chaîne quelconque |
address_zipcode |
adresse: code postal |
non |
chaîne quelconque |
address_city |
adresse: nom de la ville |
non |
chaîne quelconque |
address_country |
adresse: pays |
non |
chaîne quelconque |
home_phone |
téléphone fixe personnel |
non |
Peut commencer par un '+'. Ne contient ensuite que des chiffres, maximum 20. |
home_mobile_phone |
téléphone fixe personnel |
non |
Peut commencer par un '+'. Ne contient ensuite que des chiffres, maximum 20. |
professional_phone |
téléphone fixe professionnel |
non |
Peut commencer par un '+'. Ne contient ensuite que des chiffres, maximum 20. |
professional_mobile_phone |
téléphone fixe professionnel |
non |
Peut commencer par un '+'. Ne contient ensuite que des chiffres, maximum 20. |
send_registration_email |
Envoyer un email à la création de compte terminer l'enregistrement. |
non |
"True" |
send_registration_email_next_url |
Adresse sur laquelle rediriger l'utilisateur après l'enregistrement. |
URL valide |
Les valeurs null
ne sont pas autorisées.
La validité INSEE des champs birthplace, birthplace_insee, birthcountry et birthcountry_insee, ainsi que la cohérence entre birthplace et birthplace_insee et entre birthcountry et birthcountry_insee, est à la charge du client.
Exemple¶
POST /api/users/ HTTP/1.1
Content-Type: application/json
Authorization: Basic xxxx
Content-Length: xxx
{
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"gender": 1,
"email": "john.doe@example.com",
"birthdate": "1981-06-01",
"birthplace": "Marseille",
"birthcountry": "France",
"preferred_username": "john",
"address_city": "New-York",
"send_registration_email": "True",
"send_registration_email_next_url": "http://www.entrouvert.com"
}
Retour passant¶
201 Created
Content-Type: application/json
Content-Length: xxx
{
"sub": "8e7f200b4bb447fa8a91cd03c0f0ade3",
"first_name": "john",
"given_name": "john",
"last_name": "doe",
"family_name": "doe",
"email": "john.doe@entrouvert.com",
"modified": "2017-03-20T13:16:44.991343Z",
"birthplace_insee": null,
"gender": "1",
"birthcountry_insee": null,
"title": null,
"birthdate": "1981-06-01",
"birthplace": "Marseille",
"birthcountry": "France",
"preferred_username": "john
"preferred_givenname": null,
"address_number": null,
"address_street": null,
"address_complement": null,
"address_zipcode": null,
"address_city": "New-York",
"address_country": null,
"birthdepartment": null,
"comment": null,
"validated": null,
"validation_date": null,
"validation_context": null,
"home_phone": null,
"home_mobile_phone": null,
"professional_phone": null,
"professional_mobile_phone": null
}
Retour non-passant¶
Code |
Signification |
Contenu |
400 |
Le format de la requête est invalide (JSON mal formaté, attribut manquant, etc..) |
Un document JSON décrivant les erreurs rencontrées |
401 |
L'authentification a échouée |
|
403 |
Permission non accordée d'effectuer l'action |
|
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
Content-Length: xxxx
{
"errors": {
"last_name": [
"Ce champ est obligatoire."
]
},
"result": 0
}
Extension get-or-create et update-or-create¶
Dans certains cas il sera souhaite de créer uniquement si un utilisateur équivalent n'existe pas déjà (avec un même mail ou nom d'utilisateur), dans ce cas on pourra ajouter autant de fois que nécessaire les paramètres
get_or_create
ou
update_or_create
à l'URL pour indiquer les champs concernés. Ces deux champs sont exclusifs (on ne peut pas utiliser
get_or_create
et
update_or_create
en même temps). Les différents comportements dépendent du résultat de la recherche :
- si aucun utilisateur n'est trouvé la création a lieu normalement,
- si un utilisateur est trouvé :
- pour
get_or_create
, l'utilisateur est retourné avec un code 200 Ok
au lieu de 201 Created
mais aucune modification ne lui est apporté, les données postées sont ignorées,
- pour
update_or_create
, l'utilisateur est mis à jour avec les données postées puis retourné avec un code 200 Ok
,
- si plusieurs utilisateurs sont trouvés l'opération échouera avec une erreur.
Exemple (email dans l'URL doit être écrit littéralement, il ne faut pas indiquer un courriel ou une variable)
POST /api/users/?get_or_create=email HTTP/1.1
Content-Type: application/json
Authorization: Basic xxxx
Content-Length: xxx
{
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"gender": 1,
"email": "john.doe@example.com",
"birthdate": "1981-06-01",
"birthplace": "Marseille",
"birthcountry": "France",
"preferred_username": "john",
"address_city": "New-York",
"send_registration_email": "True",
"send_registration_email_next_url": "http://www.entrouvert.com"
}
200 Ok
Content-Type: application/json
{
"sub": "8e7f200b4bb447fa8a91cd03c0f0ade3",
"first_name": "john",
"given_name": "john",
"last_name": "doe",
"family_name": "doe",
"email": "john.doe@examle.com",
"modified": "2017-03-20T13:16:44.991343Z",
}
Exemple avec clé multiple :
POST /api/users/?update_or_create=first_name&update_or_create=last_name HTTP/1.1
Content-Type: application/json
Authorization: Basic xxxx
Content-Length: xxx
{
"email": "john.doe2@example.net",
"first_name": "john",
"last_name": "doe",
}
200 Ok
Content-Type: application/json
{
"sub": "8e7f200b4bb447fa8a91cd03c0f0ade3",
"first_name": "John",
"given_name": "Doe",
"last_name": "doe",
"family_name": "doe",
"email": "john.doe2@examle.com",
"modified": "2017-03-20T13:16:44.991343Z",
}
Lecture d'un comptes¶
URL |
Méthode |
Contenu |
Paramètres |
/api/users/<id_compte>/ |
GET |
document JSON décrivant le compte lu |
non |
GET /api/users/<id_compte>/ HTTP/1.1
Authorization: Basic xxxx
Retour passant¶
Code |
Signification |
Contenu |
200 |
Un document JSON décrivant le compte |
200 Ok
Content-Type: application/json
Content-Length: xxxx
{
"sub": "8e7f200b4bb447fa8a91cd03c0f0ade3",
"first_name": "john",
"given_name": "john",
"last_name": "doe",
"family_name": "doe",
"email": "john.doe@example.com",
"modified": "2017-03-20T13:16:44.991343Z",
"birthplace_insee": null,
"gender": "1",
"birthcountry_insee": null,
"title": null,
"birthdate": "1981-06-01",
"birthplace": "Marseille",
"birthcountry": "France",
"preferred_username": "ben",
"preferred_givenname": null,
"address_number": null,
"address_street": null,
"address_complement": null,
"address_zipcode": null,
"address_city": "New-York",
"address_country": null,
"birthdepartment": null,
"comment": null,
"validated": null,
"validation_date": null,
"validation_context": null,
"home_phone": null,
"home_mobile_phone": null,
"professional_phone": null,
"professional_mobile_phone": null
}
Les propriétés sans valeur sont à null
.
Retour non-passant¶
Code |
Signification |
Contenu |
401 |
L'authentification a échouée |
|
403 |
Permission non accordée d'effectuer l'action |
|
404 |
L'id compte donné n'existe pas |
|
voir plus haut
Modification d'un comptes¶
URL |
Méthode |
Contenu |
Paramètres |
/api/users/<id_compte>/ |
PUT |
document JSON décrivant le compte |
non |
/api/users/<id_compte>/ |
PATCH |
document JSON décrivant le compte |
non |
PATCH /api/users/<id_compte>/ HTTP/1.1
Content-Type: application/json
Authorization: Basic xxxx
Content-Length: xxx
{
"validated": "True",
"validation_date": "2016-11-23",
"validation_context": "FC"
}
L'action PUT nécessite que first_name
et last_name
(obligatoires) soient dans le document JSON. S'ils ne sont pas renseignés, une erreur 400 est retournée.
La validité INSEE des champs birthplace, birthplace_insee, birthcountry et birthcountry_insee, ainsi que la cohérence entre birthplace et birthplace_insee et entre birthcountry et birthcountry_insee, est à la charge du client.
Attention : gender, family_name et given_name sont des alias des attributs title, last_name et firstname, avec gender où Madame est traduit en female et Monsieur en male. Lorsque l'on souhaite modifier ces attributs, cela doit porter sur les attributs title, last_name et firstname et non sur gender, family_name et given_name.
Attention : l'attribut email n'est pas modifiable par ce service. Sa modification nécessite l'utilisation d'un "service dédié au changement d'email":#Envoyer-un-jeton-pour-modifier-lemail
Retour passant¶
Code |
Signification |
Contenu |
200 |
Ok |
Un document JSON décrivant le compte modifié |
200 Ok
Content-Type: application/json
Content-Length: xxx
{
"sub": "8e7f200b4bb447fa8a91cd03c0f0ade3",
"first_name": "john",
"given_name": "john",
"last_name": "doe",
"family_name": "doe",
"email": "john.doe@example.com",
"modified": "2017-03-20T13:16:44.991343Z",
"birthplace_insee": null,
"gender": "1",
"birthcountry_insee": null,
"title": null,
"birthdate": "1981-06-01",
"birthplace": "Marseille",
"birthcountry": "France",
"preferred_username": "ben",
"preferred_givenname": null,
"address_number": null,
"address_street": null,
"address_complement": null,
"address_zipcode": null,
"address_city": "New-York",
"address_country": null,
"birthdepartment": null,
"comment": null,
"validated": "True",
"validation_date": null,
"validation_context": null,
"home_phone": null,
"home_mobile_phone": null,
"professional_phone": null,
"professional_mobile_phone": null
}
Retour non-passant¶
Code |
Signification |
Contenu |
400 |
Le format de la requête est invalide (JSON mal formaté, attribut manquant, etc..) |
Un document JSON décrivant les erreurs rencontrées |
401 |
L'authentification a échouée |
|
403 |
Permission non accordée d'effectuer l'action |
|
404 |
L'id compte donné n'existe pas |
|
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
Content-Length: xxxx
{
"errors": {
"last_name": [
"Ce champ est obligatoire."
]
},
"result": 0
}
Suppression d'un compte¶
URL |
Méthode |
Contenu |
Paramètres |
/api/users/<id_compte>/ |
DELETE |
aucun |
non |
DELETE /api/users/<id_compte>/ HTTP/1.1
Authorization: Basic xxx
Retour passant¶
Code |
Signification |
Contenu |
204 |
Ok |
aucun |
204 No content
Retour non-passant¶
Code |
Signification |
Contenu |
400 |
Le format de la requête est invalide (JSON mal formaté, attribut manquant, etc..) |
Un document JSON décrivant les erreurs rencontrées |
401 |
L'authentification a échouée |
|
403 |
Permission non accordée d'effectuer l'action |
|
404 |
L'id compte donné n'existe pas |
JSON d'erreur |
Forcer le changement de mot de passe à la prochaine connexion¶
URL |
Méthode |
Contenu |
Paramètres |
/api/users/<id_compte>/force-password-reset/ |
POST |
aucun |
non |
POST /api/users/<id_compte>/force-password-reset/ HTTP/1.1
Authorization: Basic xxx
Retour passant¶
Code |
Signification |
Contenu |
204 |
Ok |
aucun |
204 No content
Retour non-passant¶
Code |
Signification |
Contenu |
400 |
Le format de la requête est invalide (JSON mal formaté, attribut manquant, etc..) |
Un document JSON décrivant les erreurs rencontrées |
401 |
L'authentification a échouée |
|
403 |
Permission non accordée d'effectuer l'action |
|
404 |
L'id compte donné n'existe pas |
JSON d'erreur |
Tests d'existence des comptes en masse¶
Ce web-service doit être utilisé pour la propagation des suppressions de compte. L'appel peut-être fait soit au moment de la détection d'une collision (compte nouveau arrivant avec un email existant), avec envoi du sub du compte existant, soit en masse régulièrement, avec envoi en plusieurs fois (par paquet de 100) de la totalité des subs connus.
URL |
Méthode |
Contenu |
Paramètres |
/api/users/synchronization/ |
POST |
Document JSON contenant la liste des ID compte à tester |
non |
POST /api/users/synchronization/ HTTP/1.1
Authorization: Basic xxx
Content-Type: application/json
Content-Length: xxxx
{
"known_uuids":["e46d46ebcb1d4d6bac4571159b542389", "1234567890"],
}
Retour passant¶
200 Ok
Content-Type: application/json
Content-Length: xxxx
{
"unknown_uuids":["1234567890"],
"result":1
}
Retour non-passant¶
Code |
Signification |
Contenu |
400 |
Le format de la requête est invalide (JSON mal formaté, attribut manquant, etc..) |
Un document JSON décrivant les erreurs rencontrées |
401 |
L'authentification a échouée |
|
403 |
Permission non accordée d'effectuer l'action |
|
400 BadRequest
Content-Type: application/json
Content-Length: xxxx
{
"detail":"JSON parse error - Expecting ',' delimiter: line 1 column 53 (char 52)"
}
Supprimer une fédération FranceConnect¶
URL |
Méthode |
Contenu |
Paramètres |
/api/users/<id_compte>/fc-unlink/ |
DELETE |
aucun |
non |
DELETE /api/users/<id_compte>/fc-unlink/ HTTP/1.1
Authorization: Basic xxx
Retour passant¶
Code |
Signification |
Contenu |
204 |
Ok |
aucun |
204 No content
Retour non-passant¶
Code |
Signification |
Contenu |
400 |
Le format de la requête est invalide (JSON mal formaté, attribut manquant, etc..) |
Un document JSON décrivant les erreurs rencontrées |
401 |
L'authentification a échouée |
|
403 |
Permission non accordée d'effectuer l'action |
404 |
L'id compte donné n'existe pas |
JSON d'erreur |
Envoyer un jeton pour reinitialisation de mot de passe¶
URL |
Méthode |
Contenu |
Paramètres |
/api/users/<id_compte>/password-reset/ |
POST |
aucun |
non |
POST /api/users/<id_compte>/password-reset/ HTTP/1.1
Authorization: Basic xxx
Retour passant¶
Code |
Signification |
Contenu |
204 |
Ok |
aucun |
204 No content
Retour non-passant¶
Code |
Signification |
Contenu |
400 |
Le format de la requête est invalide (JSON mal formaté, attribut manquant, etc..) |
Un document JSON décrivant les erreurs rencontrées |
401 |
L'authentification a échouée |
|
403 |
Permission non accordée d'effectuer l'action |
404 |
L'id compte donné n'existe pas |
JSON d'erreur |
500 |
L'utilisateur identifié par l'id compte n'a pas de couriel |
JSON d'erreur |
Envoyer un jeton pour modifier l'email¶
URL |
Méthode |
Contenu |
Paramètres |
/api/users/<id_compte>/email/ |
POST |
aucun |
non |
POST /api/users/<id_compte>/email/ HTTP/1.1
Authorization: Basic xxx
{"email": "nouvelemail@example.com"}
Retour passant¶
Code |
Signification |
Contenu |
204 |
Ok |
aucun |
200 No content
Content-Type: application/json
{"result": 1}
Retour non-passant¶
Code |
Signification |
Contenu |
400 |
Le format de la requête est invalide (JSON mal formaté, attribut manquant, etc..) |
Un document JSON décrivant les erreurs rencontrées |
401 |
L'authentification a échouée |
|
403 |
Permission non accordée d'effectuer l'action |
404 |
L'id compte donné n'existe pas |
JSON d'erreur |
Demande de validation de compte¶
Pour éviter les problématiques de validation des pièces jointes, seul le format JPEG est autorisé au niveau de l'API portée par le compte. Charge aux clients de l'API de convertir d'autres formats en JPEG.
URL |
Méthode |
Contenu |
Paramètres |
/api/users/<id_compte>/validate/ |
POST |
application/json |
non |
POST /api/users/<id_compte>/validate/ HTTP/1.1
Authorization: Basic xxx
Content-Type: application/json
Le champ external_id
représente l'identifiant de la demande dans le SI du demandeur, il permet d'empêcher les doublons. Le couple (id_compte
, external_id
) doit être unique, sinon la création de la demande est rejetée.
{
"justificatifs": [{
"b64_content": "..."
}],
"external_id": "XYZ1234"
}
Le champs justificatifs
est une liste de dictionnaire contenant une unique clé b64_content
. Chaque dictionnaire représente une page du justificatif, jusqu'à 2. Chaque page doit peser moins de 300Ko, sinon la demande est rejetée, et doit être un fichier JPEG encodé en base64 dans une chaîne JSON.
Retour passant¶
Code |
Signification |
Contenu |
201 |
Created |
application/json |
201 Created
Content-Type: application/json
{
"result": 1,
"status": "received",
"sub": "xyz1234543534535",
"external_id": "32423424324",
"id": 123
}
Retour non passant¶
À noter qu'il est interdit de créer plusieurs demandes pour un même external_id
pour un partenaire donné mais que plusieurs demandes pour un même id_compte
(même usager) peuvent être créée. C'est au partenaire de décider dans son système s'il autorise cela.
Code |
Signification |
Contenu |
400 |
Le format de la requête est invalide (JSON mal formaté, attribut manquant, etc..) |
Un document JSON décrivant les erreurs rencontrées |
404 |
L'id compte donné n'existe pas |
|
401 |
L'authentification a échoué |
|
403 |
Permission non accordée d'effectuer l'action |
|
413 |
Entity too large |
la requête dépasse la limite dur du serveur web (disons 5x la limite par justificatif) |
400 Bad Request
Content-Type: application/json
{
"result": 0,
"errors": [
{
'code': 'justificatifs-bad-format',
'page': 0,
'accepted': ['image/jpeg'],
},
{
'code': 'justificatifs-too-big',
'page': 0,
'max-size': '300000',
}
{
'code': 'already-exists',
}
]
}
Liste des codes d'erreur
Code |
Paramètres |
Signification |
justificatifs-bad-format |
page: l'index du justificatif qui pose problème, accepted: la liste des types MIME acceptés |
une des pièces jointes n'est pas dans un des formats autorisés |
justificatifs-too-big |
page: l'index du justificatif qui pose problème, max-size: la taille maximum acceptée |
une des pièces jointes dépasse la taille autorisée |
already-exists |
Aucun |
la demande a déjà été créé |
schema-error |
field: le champ JSON concerné sub-errors: une liste de chaîne expliquant l'erreur ou un dictionnaire si l'erreur est dans un sous-champ (ici uniquement b64_content) |
le format du document JSON envoyé ne correspond pas à ce qui est attendu. Ce code signale une erreur dans le code appelant qui ne respecte pas le format du document JSON attendu. |
Lister les demandes de validation¶
La liste est paginée (comme pour le listing des compte), par groupe de 100. L'ordre est l'ordre croissant de la date de création. Voir cette "section":#Pagination-des-r%C3%A9sultats pour l'utilisation de la pagination.
Les demandes traitées ayant plus d'un mois sont purgées.
URL |
Méthode |
Contenu |
Paramètres |
/api/validate/ |
GET |
non |
voir plus loin |
/api/users/<id_compte>/validate/ |
GET |
non |
voir plus loin |
La version avec l'id_compte
ne liste que les demandes concernant cet ID compte.
Paramètres¶
Nom |
Sémantique |
Valeurs permises |
Exemple |
validated__gt |
Liste les demandes validées, acceptées ("status": "accepted" ) ou refusées ("status": "refused" ) après la date indiquée. Ne s'applique que sur /api/validate/. |
date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SSZ |
|
Retour passant¶
Code |
Signification |
Contenu |
200 |
OK |
application/json |
200 OK
Content-Type: application/json
{
"next": null,
"previous": null,
"result": 1,
"results": [
{
"created": "2018-04-24T06:49:37.371577Z",
"external_id": "7",
"id": 9,
"reason": "",
"status": "received",
"sub": "YTIBAQCbZndVIpit-Eog-Y-33sFBf9hTbHYa4YVxDfqW6kwmJWo3_5glGQtGbzQI7FajXtw",
"validated": null
},
...
{
"created": "2018-04-23T17:03:16.791785Z",
"external_id": "4",
"id": 6,
"reason": "",
"status": "accepted",
"sub": "YTIBAQCbZndVIpit-Eog-Y-33sFBf9hTbHYa4YVxDfqW6kwmJWo3_5glGQtGbzQI7FajXtw",
"validated": "2018-04-23T17:06:52.623275Z"
},
{
"created": "2018-04-23T17:01:46.458133Z",
"external_id": "3",
"id": 5,
"reason": "underaged",
"status": "refused",
"sub": "YTIBAQCbZndVIpit-Eog-Y-33sFBf9hTbHYa4YVxDfqW6kwmJWo3_5glGQtGbzQI7FajXtw",
"validated": "2018-04-23T17:04:52.121961Z"
},
{
"created": "2018-04-23T16:59:24.773830Z",
"external_id": "2",
"id": 4,
"reason": "unreadable",
"status": "refused",
"sub": "YTIBAQCbZndVIpit-Eog-Y-33sFBf9hTbHYa4YVxDfqW6kwmJWo3_5glGQtGbzQI7FajXtw",
"validated": "2018-04-23T17:01:02.989202Z"
},
{
"created": "2018-04-23T16:44:24.223940Z",
"external_id": "1",
"id": 3,
"reason": "invalid",
"status": "refused",
"sub": "YTIBAQCbZndVIpit-Eog-Y-33sFBf9hTbHYa4YVxDfqW6kwmJWo3_5glGQtGbzQI7FajXtw",
"validated": "2018-04-23T16:57:50.874902Z"
},
...
]
}
Le champ
status
peut contenir trois valeurs différentes :
received
pour les nouvelles demande non encore traitées,
accepted
pour les demandes acceptées,
refused
pour les demandes refusées, la raison se trouvant dans le champ reason
qui est une chaîne de texte.
Le champ
reason
est un code parmi les valeurs suivantes :
Valeur |
Signification |
unreadable |
L'agent n'est pas parvenu à lire la ou les pièces jointes. |
invalid |
La pièce jointe ne correspond pas à une pièce jointe acceptable (à déterminer dans la convention de partenariat et pas dans du code) ou elle n'est pas complète ou elle est périmée. |
underaged |
L'usager est mineur. |
Lorsqu'une demande passe du statut "received"
à "accepted"
ou "refused"
, la date de la transition est conservée dans le champs validated
. Le fait de filtrer à l'aide de validated__gt
ne renvoie que des demandes validées ("status": "accepted"
ou "status": "refused"
), donc dont le champs validated
n'est pas null
.
Retour non passant¶
Code |
Signification |
Contenu |
401 |
L'authentification a échoué |
|
403 |
Permission non accordée d'effectuer l'action |
|
404 |
L'id compte donné n'existe pas |
|