Authentification

Markdown

Ce guide vous accompagne pour vous authentifier auprès du Human Dashboard et générer la x-unico-accesskey que vous utiliserez dans toutes les requêtes de l'API Human Token.

Le flux comporte deux phases :

S'authentifier — effectuer une connexion et obtenir un jeton d'accès. Deux méthodes d'authentification sont disponibles :
- Connexion biométrique — capture du visage via le Unico SDK (disponible pour l'inscription comme pour la connexion)
- Connexion par OTP e-mail — code à usage unique envoyé à l'adresse e-mail enregistrée (connexion uniquement)
Configurer votre organisation — créer le profil de votre entreprise et générer une clé d'accès (uniquement lors de la première inscription)

Deux façons de configurer vos identifiants

Tout ce que décrit ce guide peut également être réalisé via le Human Dashboard sur dashboard.unico.app — aucun appel d'API n'est nécessaire.

Option	Quand l'utiliser
Dashboard	Première configuration, rotation manuelle des clés, gestion ponctuelle
API	Provisionnement automatisé, pipelines CI/CD, gestion programmatique des clés

Utiliser le dashboard

Accédez à dashboard.unico.app
Inscrivez-vous ou connectez-vous — utilisez la connexion biométrique (capture du visage) ou l'OTP par e-mail
Créez votre organisation — renseignez le nom de votre entreprise, le pays et les domaines autorisés
Générez une clé d'accès — accédez à Access Keys et cliquez sur Create key ; copiez-la immédiatement, elle n'est affichée qu'une seule fois
Gérez les branches — créez et configurez des branches sous Branches ; chaque branche génère sa propre clé d'accès

La clé d'accès obtenue depuis le dashboard est la même x-unico-accesskey utilisée dans toutes les requêtes d'API — les deux approches sont entièrement interchangeables.

URL de base

Tous les endpoints de cette page sont servis par la Human Dashboard API. Les requêtes de l'API Human Token, comme Create Process et Get Process, sont envoyées à l'hôte de l'API indiqué dans Environnements.

Environnement	API	URL de base
Production	Human Dashboard API (connexion, organisation, clés d'accès et branches)	`https://api.humantoken.unico.app`

Méthodes d'authentification

Deux méthodes sont disponibles pour s'authentifier et obtenir un authToken :

Méthode	Endpoint	Quand l'utiliser
Biométrique	`POST /api/console/v1/auth/biometric/sessions`	Inscription (nouveau compte) ou connexion (utilisateur existant)
OTP e-mail	`POST /api/console/v1/auth/email/sessions`	Connexion uniquement — le compte doit déjà exister

Intention de la connexion biométrique

Chaque appel à POST /api/console/v1/auth/biometric/sessions doit déclarer un intent :

`intent`	Quand l'utiliser	Champ `email`	Champ `name`
`LOGIN_INTENT_SIGNUP`	Première inscription — création d'un nouveau compte	Obligatoire	Obligatoire
`LOGIN_INTENT_SIGNIN`	Utilisateur existant — le compte existe déjà	Non utilisé	Non utilisé
(omis)	Traité comme `LOGIN_INTENT_SIGNIN`	Non utilisé	Non utilisé

L'intention détermine la validation effectuée lorsque vous interrogez la session (étape 2) :

SIGNUP — rejette la connexion si cette identité biométrique est déjà enregistrée (empêche les comptes en double).
SIGNIN — rejette la connexion si cette identité biométrique n'est pas enregistrée (le compte doit exister pour se connecter).

Phase 1 — S'authentifier

Étape 1 : démarrer une session de connexion biométrique

SIGNUP (première inscription)

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNUP",
    "email": "[email protected]",
    "name": "Jane Doe"
  }'

Unicité de l'e-mail

Si un compte est déjà enregistré avec cet e-mail, la requête renvoie 400 Bad Request.

Réponse :

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "",
    "token": ""
  }
}

Pour SIGNUP, les champs link et token sont vides dans la réponse — le lien de capture biométrique est envoyé à l'adresse e-mail fournie.

SIGNIN (utilisateur existant)

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNIN"
  }'

Réponse :

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "https://humantoken.unico.io/...",
    "token": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

Enregistrez le sessionId.

SIGNUP : le lien de capture biométrique est envoyé à l'e-mail fourni à l'étape 1. Demandez à l'utilisateur de consulter sa boîte de réception et d'effectuer la capture.
SIGNIN : ouvrez link dans votre navigateur et effectuez la capture biométrique.

Étape 2 : interroger jusqu'à la résolution de la session

curl https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions/b3f1a2c4-0000-0000-0000-abcdef012345

Interrogez l'API toutes les 2 à 3 secondes jusqu'à ce que status atteigne un état final.

`status`	`outcome`	Signification
`pending`	`pending`	L'utilisateur n'a pas encore effectué la capture — continuez à interroger
`processing`	`pending`	Capture effectuée, résultats en cours de calcul — continuez à interroger
`completed`	`matched`	Connexion réussie — `authToken` est présent
`completed`	`no_match`	La biométrie ne correspond à aucun enregistrement
`completed`	`inconclusive`	La capture a réussi mais n'a pas pu être résolue
`expired`	—	Lien expiré — recommencez à l'étape 1
`canceled`	—	Session annulée — recommencez à l'étape 1

Erreurs supplémentaires propres à chaque intention lors de l'interrogation de la session :

HTTP	Condition
`400`	SIGNUP — l'identité biométrique est déjà enregistrée (compte en double)
`400`	SIGNIN — l'identité biométrique n'est pas enregistrée (le compte n'existe pas)

Réponse en cas de succès :

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

Enregistrez authToken — utilisez-le comme en-tête x-console-authorization dans toutes les requêtes suivantes à la Human Dashboard API.

Phase 1 (alternative) — Connexion par OTP e-mail

Utilisez ce flux à la place du flux biométrique si l'utilisateur possède déjà un compte et préfère s'authentifier au moyen d'un code à usage unique envoyé à son e-mail enregistré. L'inscription n'est pas prise en charge via l'OTP e-mail — utilisez le flux biométrique pour la première inscription.

Étape 1 : envoyer l'OTP

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/email/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

remarque

L'e-mail doit appartenir à un compte existant. Si aucun compte n'est trouvé, l'étape 2 (valider l'OTP) renvoie 404 Not Found.

Réponse :

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345"
  }
}

Enregistrez le sessionId. Un code à 6 chiffres est envoyé à l'adresse e-mail fournie.

Étape 2 : valider l'OTP

curl https://api.humantoken.unico.app/api/console/v1/auth/email/sessions/{sessionId}/{code}

HTTP	Condition
`200`	Le code est valide — `authToken` est présent
`400`	Le code est incorrect (`invalid otp code`)
`400`	OTP déjà utilisé, nombre maximal de tentatives atteint ou expiré
`404`	E-mail non enregistré

Réponse en cas de succès :

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

Enregistrez authToken — utilisez-le comme en-tête x-console-authorization dans toutes les requêtes suivantes à la Human Dashboard API.

Phase 2 — Configurer votre organisation

Étape 3 : créer votre organisation

remarque

Cet appel ne peut être effectué qu'une seule fois. Il provisionne votre tenant et génère votre branchId.

Tous les pays sont acceptés. Utilisez le code à trois lettres ISO 3166-1 alpha-3 (par ex. BRA, USA, MEX, DEU, IND). taxId est facultatif pour tous les pays.

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "logo": "https://acme.com/logo.png",
    "allowedDomains": ["https://app.acme.com"]
  }'

Réponse :

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

Enregistrez branchId — il identifie votre branche par défaut et sert à gérer les branches et les clés d'accès.

Étape 4 : créer une clé d'accès

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "production-key"
  }'

Réponse :

{
  "accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"
}

avertissement

L'accessKey n'est renvoyée qu'une seule fois et ne peut pas être récupérée ultérieurement. Stockez-la immédiatement dans votre gestionnaire de secrets sous le nom HUMAN_TOKEN_ACCESS_KEY.

Cette valeur est l'en-tête x-unico-accesskey utilisé dans toutes les requêtes de l'API Human Token.

Ce dont vous disposez désormais

Valeur	Où l'utiliser
`branchId`	Identifier votre branche par défaut ; créer des clés d'accès propres à une branche
`accessKey`	En-tête `x-unico-accesskey` dans toutes les requêtes Human Token

Gérer votre organisation

Obtenir l'organisation

curl https://api.humantoken.unico.app/api/console/v1/organization/<organizationId> \
  -H "x-console-authorization: <authToken>"

Réponse :

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

Mettre à jour l'organisation

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "taxId": "12345678000195",
    "logo": "https://acme.com/logo-updated.png",
    "allowedDomains": ["https://app.acme.com", "https://checkout.acme.com"]
  }'

Gérer les clés d'accès

Lister les clés (métadonnées uniquement — le secret n'est jamais renvoyé) :

curl https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>"

Effectuer la rotation d'une clé (l'ancienne clé est immédiatement invalidée) :

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys/rotate \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

Révoquer une clé (irréversible) :

curl -X DELETE https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

Gérer les branches

Les branches vous permettent de segmenter la configuration de votre organisation (nom, logo, domaines autorisés) par produit ou par environnement. Chaque branche possède ses propres clés d'accès : le contexte de branche est donc résolu automatiquement à partir de la clé utilisée dans la requête — inutile de transmettre branchId dans CreateProcess.

Créer une branche

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App",
    "logo": "https://acme.com/mobile-logo.png",
    "allowedDomains": ["https://mobile.acme.com"]
  }'

Réponse :

{
  "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
}

Enregistrez branchId — utilisez-le pour créer une clé d'accès propre à une branche.

Mettre à jour une branche

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345",
    "name": "Mobile App v2",
    "logo": "https://acme.com/mobile-logo-v2.png",
    "allowedDomains": ["https://mobile.acme.com", "https://app.acme.com"]
  }'

Créer une clé d'accès propre à une branche

Pour générer une clé d'accès limitée à une branche précise, incluez branchId dans le corps de la requête :

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "mobile-app-key",
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
  }'

Réponse :

{
  "accessKey": "uip_ak.prod.z9y8x7w6.v5u4t3s2.r1q0p9o8"
}

avertissement

L'accessKey n'est renvoyée qu'une seule fois. Stockez-la immédiatement. Toute requête CreateProcess authentifiée avec cette clé utilisera automatiquement la configuration de branche qui lui est associée.

Deux façons de configurer vos identifiants​

Utiliser le dashboard​

URL de base​

Méthodes d'authentification​

Intention de la connexion biométrique​

Phase 1 — S'authentifier​

Étape 1 : démarrer une session de connexion biométrique​

Étape 2 : interroger jusqu'à la résolution de la session​

Phase 1 (alternative) — Connexion par OTP e-mail​

Étape 1 : envoyer l'OTP​

Étape 2 : valider l'OTP​

Phase 2 — Configurer votre organisation​

Étape 3 : créer votre organisation​

Étape 4 : créer une clé d'accès​

Ce dont vous disposez désormais​

Gérer votre organisation​

Obtenir l'organisation​

Mettre à jour l'organisation​

Gérer les clés d'accès​

Gérer les branches​

Créer une branche​

Mettre à jour une branche​

Créer une clé d'accès propre à une branche​

Deux façons de configurer vos identifiants

Utiliser le dashboard

URL de base

Méthodes d'authentification

Intention de la connexion biométrique

Phase 1 — S'authentifier

Étape 1 : démarrer une session de connexion biométrique

Étape 2 : interroger jusqu'à la résolution de la session

Phase 1 (alternative) — Connexion par OTP e-mail

Étape 1 : envoyer l'OTP

Étape 2 : valider l'OTP

Phase 2 — Configurer votre organisation

Étape 3 : créer votre organisation

Étape 4 : créer une clé d'accès

Ce dont vous disposez désormais

Gérer votre organisation

Obtenir l'organisation

Mettre à jour l'organisation

Gérer les clés d'accès

Gérer les branches

Créer une branche

Mettre à jour une branche

Créer une clé d'accès propre à une branche