/auth

POST

Crée une demande d’identification.

Lance une demande d’identification. Utilisez la méthode /collect pour connaître l’état de la demande.

Corps de la requête

application/json

app objet

Données supplémentaires quand la demande est créée depuis votre application.

Vous pouvez envoyer le paramètre web ou app, pas les deux. Si vous l’envoyez, au moins un de ses membres doit être renseigné : appIdentifier, deviceOS, deviceModelName, deviceIdentifier.

endUserIp chaîne Obligatoire

L’adresse IP de l’utilisateur, telle que votre service la voit. IPv4 et IPv6 sont acceptées.

Assurez-vous que l’adresse IP envoyée dans endUserIp est celle de l’appareil de l’utilisateur, et non l’adresse interne d’un proxy inverse entre vous et lui.

Quand l’adresse IP n’est pas disponible (services vocaux, par exemple), la représentation interne de l’adresse IP de ces systèmes est acceptable.

returnRisk booléen

Si la valeur est true, une indication de risque est incluse dans la réponse de /collect à la fin de la demande. L’indication exige que endUserIp soit correct. Voir Indication de risque.

returnUrl chaîne

Les demandes lancées sur l’appareil même où se trouve l’ExcelID de l’utilisateur (lancées avec l’autoStartToken) appellent cette adresse à la fin de la demande.

L’adresse de retour doit contenir un nonce lié à la session. Quand l’utilisateur revient sur votre application ou votre page web, votre service doit vérifier que la demande s’est bien terminée et que l’appareil qui reçoit la returnUrl est celui qui a lancé la demande.

Utiliser ce paramètre rend votre service plus sûr et renforce le lien entre vous et l’utilisateur. Voir URL de retour.

userNonVisibleData chaîne

Données que vous souhaitez inclure sans les afficher à l’utilisateur. Elles vous sont renvoyées telles quelles dans completionData.

La valeur doit être encodée en Base64.

userVisibleData chaîne

Texte affiché à l’utilisateur pendant la demande. Son but est de donner du contexte pour permettre à l’utilisateur de repérer des erreurs d’identification et d’éviter des tentatives de fraude.

Le texte peut être mis en forme avec CR, LF et CRLF pour les retours à la ligne. Il doit être encodé en UTF-8 puis en Base64. 1 500 caractères au plus.

userVisibleDataFormat chaîne

Si la valeur est simpleMarkdownV1, userVisibleData contient des caractères de mise en forme.

plaintext : texte Base64 en UTF-8 avec CR, LF ou CRLF pour les retours à la ligne. simpleMarkdownV1 : Markdown simplifié, version 1. Voir Mise en forme du texte.

web objet

Données supplémentaires quand la demande est créée depuis votre page web : referringDomain, userAgent, deviceIdentifier.

Vous pouvez envoyer le paramètre web ou app, pas les deux.

requirement objet

Exigences sur la façon d’effectuer l’identification.

personalNumber (chaîne, 6 à 20 lettres ou chiffres) : adresse la demande à une personne précise. Elle la reçoit dans son application, sans code QR. stepUp (liste) : contrôles supplémentaires exigés, par exemple ["document"]. Voir Contrôle supplémentaire.

Exemples

Identification lancée depuis une page web

{
  "endUserIp": "196.28.245.10",
  "returnUrl": "https://monservice.example/auth/connexion#nonce=a3618c72-bc71-4002-b3de-509555b175db",
  "userVisibleData": "Q29ubmV4aW9uIMOgIE1vbiBTZXJ2aWNl",
  "returnRisk": true,
  "web": {
    "referringDomain": "monservice.example",
    "userAgent": "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 Chrome/120 Mobile Safari/537.36",
    "deviceIdentifier": "f1e3813ab36f114d4b0c2b3636617511467adb353ce8e5ae6c83500d932f2269"
  }
}

Identification lancée depuis une application

{
  "endUserIp": "196.28.245.10",
  "userVisibleData": "Q29ubmV4aW9uIMOgIE1vbiBTZXJ2aWNl",
  "app": {
    "appIdentifier": "bf.monservice.app",
    "deviceOS": "Android 14",
    "deviceModelName": "Motorola moto g",
    "deviceIdentifier": "f1e3813ab36f114d4b0c2b3636617511467adb353ce8e5ae6c83500d932f2269"
  }
}

Exigence de numéro d’identité avec texte visible

{
  "endUserIp": "196.28.245.10",
  "userVisibleData": "Q29ubmV4aW9uIMOgIE1vbiBTZXJ2aWNl",
  "requirement": { "personalNumber": "B1234567" }
}

Requête simple

{ "endUserIp": "196.28.245.10" }

Exiger un contrôle supplémentaire par la pièce d’identité

{
  "endUserIp": "196.28.245.10",
  "requirement": { "stepUp": ["document"] }
}

Réponses

200 400 401 403 404 405 408 415 500 503 Voir Erreurs.

200 · Requête réussie

orderRef chaîne Obligatoire

Référence de la demande. Elle sert à connaître l’état de la demande ou à l’annuler.

autoStartToken chaîne Obligatoire

Sert à composer le lien de démarrage automatique.

qrStartToken chaîne Obligatoire

Sert à calculer le code QR animé.

qrStartSecret chaîne Obligatoire

Sert à calculer le code QR animé. Ne l’envoyez jamais à votre frontend.

{
  "orderRef": "131daac9-16c6-4618-beb0-365768f37288",
  "autoStartToken": "7c40b5c9-fa74-49cf-b98c-bfe651f9a7c6",
  "qrStartToken": "67df3917-fa0d-44e5-b327-edcc928297f8",
  "qrStartSecret": "d28db9a7-4cde-429e-a983-359be676944c"
}