API Authentic¶

• Contenu
• API Authentic
  • Notes de version
  • Disclaimer
  • Aperçu
  • Transport
  • Style de l'interface
  • Authentification
  • Contrôle d'accès
    • Contrôle sur les attributs
  • Liste/recherche un compte
    • Paramètres
    • Format retour
    • Exemple cas-passant
    • Cas non-passant
    • Pagination des résultats
  • Création d'un compte
    • Format entrée
    • Exemple
    • Retour passant
    • Retour non-passant
    • Extension get-or-create et update-or-create
  • Lecture d'un comptes
    • Retour passant
    • Retour non-passant
  • Modification d'un comptes
    • Retour passant
    • Retour non-passant
  • Suppression d'un compte
    • Retour passant
    • Retour non-passant
  • Forcer le changement de mot de passe à la prochaine connexion
    • Retour passant
    • Retour non-passant
  • Tests d'existence des comptes en masse
    • Retour passant
    • Retour non-passant
  • Supprimer une fédération FranceConnect
    • Retour passant
    • Retour non-passant
  • Envoyer un jeton pour reinitialisation de mot de passe
    • Retour passant
    • Retour non-passant
  • Envoyer un jeton pour modifier l'email
    • Retour passant
    • Retour non-passant
  • Demande de validation de compte
    • Retour passant
    • Retour non passant
  • Lister les demandes de validation
    • Paramètres
    • Retour passant
    • Retour non passant

Notes de version¶

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¶

Paramètres¶

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:

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¶

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¶

Format entrée¶

Le document en entrée est un object/dictionnaire JSON avec les propriétés suivantes:

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¶

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¶

• 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¶

GET /api/users/<id_compte>/ HTTP/1.1
Authorization: Basic xxxx

Retour passant¶

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¶

voir plus haut

Modification d'un comptes¶

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¶

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¶

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¶

DELETE /api/users/<id_compte>/ HTTP/1.1
Authorization: Basic xxx

Retour passant¶

204 No content

Retour non-passant¶

Forcer le changement de mot de passe à la prochaine connexion¶

POST /api/users/<id_compte>/force-password-reset/ HTTP/1.1
Authorization: Basic xxx

Retour passant¶

204 No content

Retour non-passant¶

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.

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¶

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¶

DELETE /api/users/<id_compte>/fc-unlink/ HTTP/1.1
Authorization: Basic xxx

Retour passant¶

204 No content

Retour non-passant¶

Envoyer un jeton pour reinitialisation de mot de passe¶

POST /api/users/<id_compte>/password-reset/ HTTP/1.1
Authorization: Basic xxx

Retour passant¶

204 No content

Retour non-passant¶

Envoyer un jeton pour modifier l'email¶

POST /api/users/<id_compte>/email/ HTTP/1.1
Authorization: Basic xxx

{"email": "nouvelemail@example.com"}

Retour passant¶

200 No content
Content-Type: application/json

{"result": 1}

Retour non-passant¶

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.

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¶

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.

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',
       }
   ]
}

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.

La version avec l'id_compte ne liste que les demandes concernant cet ID compte.

Paramètres¶

Retour passant¶

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" 
        },
        ...
    ]
}

• 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.

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¶