Paramètres de compte par Account API

Qu'est-ce que Logto Account API

Le Logto Account API est un ensemble complet d'API qui donne aux utilisateurs finaux un accès direct à l'API sans avoir besoin de passer par le Management API. Voici les points forts :

Accès direct : L'Account API permet aux utilisateurs finaux d'accéder directement et de gérer leurs propres profils de compte sans nécessiter le relais du Management API.
Gestion des profils et identités des utilisateurs : Les utilisateurs peuvent gérer entièrement leurs profils et paramètres de sécurité, y compris la possibilité de mettre à jour les informations d'identité telles que l'e-mail, le téléphone et le mot de passe, ainsi que de gérer les connexions sociales. Le support de MFA et SSO arrive bientôt.
Contrôle d'accès global : Les administrateurs ont un contrôle total et global sur les paramètres d'accès et peuvent personnaliser chaque champ.
Autorisation transparente : L'autorisation est plus facile que jamais ! Utilisez simplement client.getAccessToken() pour obtenir un jeton d’accès (Access token) opaque pour OP (Logto), et attachez-le à l'en-tête Authorization comme Bearer <access_token>.

Avec le Logto Account API, vous pouvez construire un système de gestion de compte personnalisé comme une page de profil entièrement intégrée à Logto.

Voici quelques cas d'utilisation fréquents :

Récupérer le profil utilisateur
Mettre à jour le profil utilisateur
Mettre à jour le mot de passe utilisateur
Mettre à jour les identités utilisateur, y compris l'e-mail, le téléphone et les connexions sociales
Gérer les facteurs MFA (vérifications)
Gérer les sessions utilisateur
Gérer les applications autorisées par l'utilisateur (grants)

Pour en savoir plus sur les API disponibles, veuillez visiter Logto Account API Reference et Logto Verification API Reference.

remarque:

Les fonctionnalités de visualisation de compte SSO et de suppression de compte sont actuellement disponibles via les Logto Management APIs. Voir Paramètres de compte par Management API pour les détails de l'implémentation.

Comment activer l'Account API

Accédez à Console > Connexion & compte > Centre de compte.

L'Account API est désactivé par défaut, donc ses contrôles d'accès sont verrouillés. Basculez Activer l'Account API pour l'activer.

Une fois activé, configurez les permissions par champ pour les identifiants, les données de profil et l'accès aux jetons tiers. Chaque champ prend en charge Off, ReadOnly ou Edit; la valeur par défaut est Off.

Champs de sécurité :
- Les champs incluent : e-mail principal, téléphone principal, identités sociales, mot de passe et MFA.
- Avant que les utilisateurs finaux puissent modifier ces champs, ils doivent vérifier leur identité via mot de passe, e-mail ou SMS pour obtenir un ID d'enregistrement de vérification de 10 minutes. Voir Obtenir un ID d'enregistrement de vérification.
- Pour utiliser les clés de passe WebAuthn pour MFA, ajoutez les domaines de votre application frontale à WebAuthn Related Origins afin que le centre de compte et l'expérience de connexion puissent partager les clés de passe. Voir Lier une nouvelle clé de passe WebAuthn.
Champs de profil :
- Les champs incluent : nom d'utilisateur, nom, avatar, profil (autres attributs de profil standard), et données personnalisées.
- Les utilisateurs finaux peuvent modifier ceux-ci sans vérification supplémentaire.
Coffre-fort secret :
- Pour les connecteurs sociaux et d'entreprise OIDC ou OAuth, Logto coffre-fort secret stocke en toute sécurité les jetons d’accès (Access tokens) et de rafraîchissement (Refresh tokens) tiers après l'authentification. Les applications peuvent ensuite appeler des API externes, telles que la synchronisation des événements Google Calendar, sans demander aux utilisateurs de se reconnecter. La récupération des jetons devient automatiquement disponible une fois l'Account API activé.
Gestion des sessions :
- Lorsqu'elle est activée, les utilisateurs peuvent voir et gérer leurs sessions actives, y compris les informations sur l'appareil et la dernière heure de connexion. Les utilisateurs peuvent également révoquer des sessions pour se déconnecter de certains appareils.
- Ce même champ de permission Sessions contrôle également les APIs des applications autorisées par l'utilisateur (grants) (voir et révoquer les grants).
- Avant que les utilisateurs finaux puissent accéder à la gestion des sessions, ils doivent vérifier leur identité via mot de passe, e-mail ou SMS pour obtenir un ID d'enregistrement de vérification de 10 minutes. Voir Obtenir un ID d'enregistrement de vérification.

Comment accéder à l'Account API

remarque:

Pour garantir que le jeton d’accès (Access token) dispose des permissions appropriées, assurez-vous d'avoir correctement configuré les portées correspondantes dans votre configuration Logto.

Par exemple, pour l'API POST /api/my-account/primary-email, vous devez configurer la portée email; pour l'API POST /api/my-account/primary-phone, vous devez configurer la portée phone.

import { type LogtoConfig, UserScope } from '@logto/js';

const config: LogtoConfig = {
  // ...autres options
  // Ajoutez les portées appropriées qui correspondent à vos cas d'utilisation.
  scopes: [
    UserScope.Email, // Pour les APIs `{POST,DELETE} /api/my-account/primary-email`
    UserScope.Phone, // Pour les APIs `{POST,DELETE} /api/my-account/primary-phone`
    UserScope.CustomData, // Pour gérer les données personnalisées
    UserScope.Address, // Pour gérer l'adresse
    UserScope.Identities, // Pour les APIs liées à l'identité et MFA
    UserScope.Profile, // Pour gérer le profil utilisateur
    UserScope.Sessions, // Pour gérer les sessions utilisateur et les grants d'application
  ],
};

Récupérer un jeton d’accès

Après avoir configuré le SDK dans votre application, vous pouvez utiliser la méthode client.getAccessToken() pour récupérer un jeton d’accès. Ce jeton est un jeton d’accès (Access token) opaque qui peut être utilisé pour accéder à l'Account API.

Si vous n'utilisez pas le SDK officiel, vous devez définir le resource à vide pour la requête de jeton d’accès à /oidc/token.

Accéder à l'Account API en utilisant le jeton d’accès

Vous devez inclure le jeton d’accès dans le champ Authorization des en-têtes HTTP avec le format Bearer (Bearer YOUR_TOKEN) lors de l'interaction avec l'Account API.

Voici un exemple pour obtenir les informations de compte utilisateur :

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

Gérer les informations de compte de base

Récupérer les informations de compte utilisateur

Pour obtenir les données utilisateur, vous pouvez utiliser le point de terminaison GET /api/my-account.

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

Le corps de la réponse serait comme :

{
  "id": "...",
  "username": "...",
  "name": "...",
  "avatar": "..."
}

Les champs de réponse peuvent varier en fonction des paramètres du centre de compte.

Mettre à jour les informations de compte de base

Les informations de compte de base incluent le nom d'utilisateur, le nom, l'avatar, les données personnalisées et d'autres informations de profil.

Pour mettre à jour username, name, avatar, et customData, vous pouvez utiliser le point de terminaison PATCH /api/my-account.

curl -X PATCH https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"username":"...","name":"...","avatar":"..."}'

Pour mettre à jour d'autres informations de profil, y compris familyName, givenName, middleName, nickname, profile (URL de la page de profil), website, gender, birthdate, zoneinfo, locale, et address, vous pouvez utiliser le point de terminaison PATCH /api/my-account/profile.

curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"familyName":"...","givenName":"..."}'

Gérer les identifiants et autres informations sensibles

Pour des raisons de sécurité, l'Account API nécessite une couche supplémentaire d'autorisation pour les opérations impliquant des identifiants et d'autres informations sensibles.

Obtenir un ID d'enregistrement de vérification

Tout d'abord, vous devez obtenir un ID d'enregistrement de vérification avec une expiration de 10 minutes (TTL). Cela peut être utilisé pour vérifier l'identité de l'utilisateur avant de mettre à jour des informations sensibles. Cela signifie qu'une fois qu'un utilisateur a vérifié avec succès son identité via mot de passe, code de vérification par e-mail ou code de vérification par SMS, il dispose de 10 minutes pour mettre à jour ses données liées à l'authentification, y compris les identifiants, les informations d'identification, le lien de compte social et MFA.

Pour obtenir un ID d'enregistrement de vérification, vous pouvez vérifier le mot de passe de l'utilisateur ou envoyer un code de vérification à l'e-mail ou au téléphone de l'utilisateur.

Vérifier le mot de passe de l'utilisateur

curl -X POST https://[tenant-id].logto.app/api/verifications/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

Le corps de la réponse serait comme :

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Vérifier en envoyant un code de vérification à l'e-mail ou au téléphone de l'utilisateur

remarque:

Pour utiliser cette méthode, vous devez configurer le connecteur e-mail ou connecteur SMS, et vous assurer que le modèle UserPermissionValidation est configuré.

Prenons l'e-mail comme exemple, demandez un nouveau code de vérification et obtenez l'ID d'enregistrement de vérification :

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

Le corps de la réponse serait comme :

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Après avoir reçu le code de vérification, vous pouvez l'utiliser pour mettre à jour le statut de vérification de l'enregistrement de vérification.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}'

Après avoir vérifié le code, vous pouvez maintenant utiliser l'ID d'enregistrement de vérification pour mettre à jour l'identifiant de l'utilisateur.

Pour en savoir plus sur les vérifications, veuillez vous référer à Vérification de sécurité par Account API.

Envoyer une requête avec l'ID d'enregistrement de vérification

Lors de l'envoi d'une requête pour mettre à jour l'identifiant de l'utilisateur, vous devez inclure l'ID d'enregistrement de vérification dans l'en-tête de la requête avec le champ logto-verification-id.

Mettre à jour le mot de passe de l'utilisateur

Pour mettre à jour le mot de passe de l'utilisateur, vous pouvez utiliser le point de terminaison POST /api/my-account/password.

curl -X POST https://[tenant-id].logto.app/api/my-account/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

astuce:

Tout comme les mots de passe créés lors de l'inscription, les mots de passe définis via l'Account API doivent respecter la politique de mot de passe que vous avez configurée dans Console > Sécurité > Politique de mot de passe. Logto renvoie des résultats de validation détaillés et des messages d'erreur si le mot de passe ne respecte pas la politique.

Mettre à jour ou lier un nouvel e-mail

remarque:

Pour utiliser cette méthode, vous devez configurer le connecteur e-mail, et vous assurer que le modèle BindNewIdentifier est configuré.

Pour mettre à jour ou lier un nouvel e-mail, vous devez d'abord prouver la propriété de l'e-mail.

Appelez le point de terminaison POST /api/verifications/verification-code pour demander un code de vérification.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

Vous trouverez un verificationId dans la réponse, et recevrez un code de vérification dans l'e-mail, utilisez-le pour vérifier l'e-mail.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}'

Après avoir vérifié le code, vous pouvez maintenant appeler PATCH /api/my-account/primary-email pour mettre à jour l'e-mail de l'utilisateur, définissez le verificationId dans le corps de la requête comme newIdentifierVerificationRecordId.

Deux ID d'enregistrement de vérification différents:

Cette requête nécessite deux ID d'enregistrement de vérification distincts :

logto-verification-id (en-tête) : Prouve l'identité de l'utilisateur avant d'apporter des modifications sensibles. Obtenez-le en vérifiant le mot de passe de l'utilisateur ou en envoyant un code de vérification à l'e-mail ou au téléphone existant de l'utilisateur.
newIdentifierVerificationRecordId (corps) : Prouve la propriété de la nouvelle adresse e-mail. C'est le verificationRecordId retourné par l'appel POST /api/verifications/verification-code ci-dessus.

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  # Vérifie l'identité de l'utilisateur (à partir du mot de passe ou de la vérification de l'e-mail/téléphone existant)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # Le "newIdentifierVerificationRecordId" prouve la propriété du nouvel e-mail (à partir du flux de code de vérification ci-dessus)
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'

astuce:

Tout comme les e-mails collectés lors de l'inscription, tout e-mail lié via l'Account API doit passer la vérification de la liste de blocage que vous avez configurée dans Console > Sécurité > Liste de blocage. Logto rejettera la requête et renverra une erreur détaillée si l'e-mail viole la politique.

Supprimer l'e-mail de l'utilisateur

Pour supprimer l'e-mail de l'utilisateur, vous pouvez utiliser le point de terminaison DELETE /api/my-account/primary-email.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

Gérer le téléphone

remarque:

Pour utiliser cette méthode, vous devez configurer le connecteur SMS, et vous assurer que le modèle BindNewIdentifier est configuré.

Similaire à la mise à jour de l'e-mail, vous pouvez utiliser le point de terminaison PATCH /api/my-account/primary-phone pour mettre à jour ou lier un nouveau téléphone. Et utilisez le point de terminaison DELETE /api/my-account/primary-phone pour supprimer le téléphone de l'utilisateur.

Pour lier une nouvelle connexion sociale, vous devez d'abord demander une URL d'autorisation avec POST /api/verifications/social.

curl -X POST https://[tenant-id].logto.app/api/verifications/social \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}'

connectorId : L'ID du connecteur social.
redirectUri : L'URI de redirection après que l'utilisateur a autorisé l'application, vous devez héberger une page web à cette URL et capturer le rappel.
state : L'état à retourner après que l'utilisateur a autorisé l'application, c'est une chaîne aléatoire utilisée pour prévenir les attaques CSRF.

Dans la réponse, vous trouverez un verificationRecordId, conservez-le pour une utilisation ultérieure.

Après que l'utilisateur a autorisé l'application, vous recevrez un rappel à l'redirectUri avec le paramètre state. Ensuite, vous pouvez utiliser le point de terminaison POST /api/verifications/social/verify pour vérifier la connexion sociale.

curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorData":"...","verificationRecordId":"..."}'

Le connectorData est les données retournées par le connecteur social après que l'utilisateur a autorisé l'application, vous devez analyser et obtenir les paramètres de requête de l'redirectUri dans votre page de rappel, et les envelopper sous forme de JSON comme valeur du champ connectorData.

Enfin, vous pouvez utiliser le point de terminaison POST /api/my-account/identities pour lier la connexion sociale.

Deux ID d'enregistrement de vérification différents:

Cette requête nécessite deux ID d'enregistrement de vérification distincts :

logto-verification-id (en-tête) : Prouve l'identité de l'utilisateur avant d'apporter des modifications sensibles. Obtenez-le en vérifiant le mot de passe de l'utilisateur ou en envoyant un code de vérification à l'e-mail ou au téléphone existant de l'utilisateur.
newIdentifierVerificationRecordId (corps) : Identifie l'identité sociale à lier. C'est le verificationRecordId retourné par l'appel POST /api/verifications/social ci-dessus.

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  # Vérifie l'identité de l'utilisateur (à partir du mot de passe ou de la vérification de l'e-mail/téléphone existant)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # Le "newIdentifierVerificationRecordId" identifie la connexion sociale à lier (à partir du flux de vérification sociale ci-dessus)
  --data-raw '{"newIdentifierVerificationRecordId":"<verification_record_id_from_social>"}'

Pour supprimer une connexion sociale, vous pouvez utiliser le point de terminaison DELETE /api/my-account/identities.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

Lier une nouvelle clé de passe WebAuthn

remarque:

N'oubliez pas d'activer MFA et WebAuthn d'abord.

remarque:

Pour utiliser cette méthode, vous devez activer le champ mfa dans les paramètres du centre de compte.

Étape 1 : Ajouter l'origine de votre application frontale aux origines associées

Les clés de passe WebAuthn sont liées à un nom d'hôte spécifique appelé Relying Party ID (RP ID). Seules les applications hébergées sur l'origine du RP ID peuvent enregistrer ou s'authentifier avec ces clés de passe.

Étant donné que votre application frontale appelle l'Account API depuis un domaine différent de celui des pages d'authentification de Logto, vous devez configurer les Origines associées pour autoriser les opérations de clé de passe inter-origines.

Comment Logto détermine le RP ID :

Configuration par défaut : Si vous utilisez uniquement le domaine par défaut de Logto https://[tenant-id].logto.app, le RP ID est [tenant-id].logto.app
Domaine personnalisé : Si vous avez configuré un domaine personnalisé comme https://auth.example.com, le RP ID devient auth.example.com

Configurer les Origines associées :

Utilisez le point de terminaison PATCH /api/account-center pour ajouter l'origine de votre application frontale. Par exemple, si le centre de compte de votre application fonctionne sur https://account.example.com :

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}'

remarque:

WebAuthn prend en charge jusqu'à 5 étiquettes eTLD+1 uniques pour les Origines associées. Le eTLD+1 (domaine de premier niveau effectif plus une étiquette) est la partie du domaine enregistrable. Par exemple :

https://example.com, https://app.example.com, et https://auth.example.com comptent comme une étiquette (example.com)
https://shopping.com, https://shopping.co.uk, et https://shopping.co.jp comptent également comme une étiquette (shopping)
https://example.com et https://another.com comptent comme deux étiquettes

Si vous devez prendre en charge plus de 5 domaines différents en tant qu'Origines associées, consultez la documentation Related Origin Requests pour plus de détails.

Étape 2 : Demander de nouvelles options d'enregistrement

Utilisez le point de terminaison POST /api/verifications/web-authn/registration pour demander l'enregistrement d'une nouvelle clé de passe. Logto permet à chaque compte utilisateur d'enregistrer plusieurs clés de passe.

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Vous obtiendrez une réponse comme :

{
  "registrationOptions": "...",
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Étape 3 : Enregistrer la clé de passe dans le navigateur local

Prenons @simplewebauthn/browser comme exemple, vous pouvez utiliser la fonction startRegistration pour enregistrer la clé de passe dans le navigateur local.

import { startRegistration } from '@simplewebauthn/browser';

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // Les données retournées par le serveur à l'étape 1
});
// Enregistrez la réponse pour une utilisation ultérieure

Étape 4 : Vérifier l'enregistrement de la clé de passe

Utilisez le point de terminaison POST /api/verifications/web-authn/registration/verify pour vérifier l'enregistrement de la clé de passe.

Cette étape vérifie la signature cryptographique générée par l'authentificateur pour s'assurer que la clé de passe a été légitimement créée et n'a pas été altérée pendant la transmission.

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"payload":"...","verificationRecordId":"..."}'

payload : La réponse du navigateur local à l'étape 2.
verificationRecordId : L'ID d'enregistrement de vérification retourné par le serveur à l'étape 1.

Étape 5 : Lier la clé de passe

Enfin, vous pouvez lier la clé de passe au compte de l'utilisateur en utilisant le point de terminaison POST /api/my-account/mfa-verifications.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'

verification_record_id : un ID d'enregistrement de vérification valide, accordé en vérifiant le facteur existant de l'utilisateur, vous pouvez vous référer à la section Obtenir un ID d'enregistrement de vérification pour plus de détails.
type : le type du facteur MFA, actuellement seul WebAuthn est pris en charge.
newIdentifierVerificationRecordId : l'ID d'enregistrement de vérification retourné par le serveur à l'étape 1.

Gérer les clés de passe WebAuthn existantes

Pour gérer les clés de passe WebAuthn existantes, vous pouvez utiliser le point de terminaison GET /api/my-account/mfa-verifications pour obtenir les clés de passe actuelles et d'autres facteurs de vérification MFA.

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>'

Le corps de la réponse serait comme :

[
  {
    "id": "...",
    "type": "WebAuthn",
    "name": "...",
    "agent": "...",
    "createdAt": "...",
    "updatedAt": "..."
  }
]

id : l'ID de la vérification.
type : le type de la vérification, WebAuthn pour la clé de passe WebAuthn.
name : le nom de la clé de passe, champ optionnel.
agent : l'agent utilisateur de la clé de passe.

Mettre à jour le nom de la clé de passe en utilisant le point de terminaison PATCH /api/my-account/mfa-verifications/{verificationId}/name :

curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"name":"..."}'

Supprimer la clé de passe en utilisant le point de terminaison DELETE /api/my-account/mfa-verifications/{verificationId} :

curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

Lier un nouveau TOTP

remarque:

N'oubliez pas d'activer MFA et TOTP d'abord.

remarque:

Pour utiliser cette méthode, vous devez activer le champ mfa dans les paramètres du centre de compte.

Étape 1 : Générer un secret TOTP

Utilisez le point de terminaison POST /api/my-account/mfa-verifications/totp-secret/generate pour générer un secret TOTP.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Le corps de la réponse serait comme :

{
  "secret": "..."
}

Étape 2 : Afficher le secret TOTP à l'utilisateur

Utilisez le secret pour générer un code QR ou l'afficher directement à l'utilisateur. L'utilisateur doit l'ajouter à son application d'authentification (telle que Google Authenticator, Microsoft Authenticator ou Authy).

Le format URI pour le code QR doit être :

otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer]

Exemple :

otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

Étape 3 : Lier le facteur TOTP

Après que l'utilisateur a ajouté le secret à son application d'authentification, il doit le vérifier et le lier à son compte. Utilisez le point de terminaison POST /api/my-account/mfa-verifications pour lier le facteur TOTP.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"Totp","secret":"..."}'

verification_record_id : un ID d'enregistrement de vérification valide, accordé en vérifiant le facteur existant de l'utilisateur. Vous pouvez vous référer à la section Obtenir un ID d'enregistrement de vérification pour plus de détails.
type : doit être Totp.
secret : le secret TOTP généré à l'étape 1.

remarque:

Un utilisateur ne peut avoir qu'un seul facteur TOTP à la fois. Si l'utilisateur a déjà un facteur TOTP, tenter d'en ajouter un autre entraînera une erreur 422.

Gérer les codes de secours

remarque:

N'oubliez pas d'activer MFA et les codes de secours d'abord.

remarque:

Pour utiliser cette méthode, vous devez activer le champ mfa dans les paramètres du centre de compte.

Étape 1 : Générer de nouveaux codes de secours

Utilisez le point de terminaison POST /api/my-account/mfa-verifications/backup-codes/generate pour générer un nouvel ensemble de 10 codes de secours.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Le corps de la réponse serait comme :

{
  "codes": ["...", "...", "..."]
}

Étape 2 : Afficher les codes de secours à l'utilisateur

Avant de lier les codes de secours au compte de l'utilisateur, vous devez les afficher à l'utilisateur et lui indiquer de :

Télécharger ou noter ces codes immédiatement
Les stocker dans un endroit sécurisé
Comprendre que chaque code ne peut être utilisé qu'une seule fois
Savoir que ces codes sont leur dernier recours s'ils perdent l'accès à leurs méthodes MFA principales

Vous devez afficher les codes dans un format clair et facile à copier et envisager de fournir une option de téléchargement (par exemple, sous forme de fichier texte ou PDF).

Étape 3 : Lier les codes de secours au compte utilisateur

Utilisez le point de terminaison POST /api/my-account/mfa-verifications pour lier les codes de secours au compte de l'utilisateur.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"BackupCode","codes":["...","...","..."]}'

verification_record_id : un ID d'enregistrement de vérification valide, accordé en vérifiant le facteur existant de l'utilisateur. Vous pouvez vous référer à la section Obtenir un ID d'enregistrement de vérification pour plus de détails.
type : doit être BackupCode.
codes : le tableau des codes de secours générés à l'étape précédente.

remarque:

Un utilisateur ne peut avoir qu'un seul ensemble de codes de secours à la fois. Si tous les codes ont été utilisés, l'utilisateur doit générer et lier de nouveaux codes.
Les codes de secours ne peuvent pas être le seul facteur MFA. L'utilisateur doit avoir au moins un autre facteur MFA (tel que WebAuthn ou TOTP) activé.
Chaque code de secours ne peut être utilisé qu'une seule fois.

Voir les codes de secours existants

Pour voir les codes de secours existants et leur statut d'utilisation, utilisez le point de terminaison GET /api/my-account/mfa-verifications/backup-codes :

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \
  -H 'authorization: Bearer <access_token>'

Le corps de la réponse serait comme :

{
  "codes": [
    {
      "code": "...",
      "usedAt": null
    },
    {
      "code": "...",
      "usedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

code : le code de secours.
usedAt : l'horodatage lorsque le code a été utilisé, null s'il n'a pas encore été utilisé.

Gérer les sessions utilisateur

Lister les sessions actives

Pour lister les sessions actives de l'utilisateur, vous pouvez utiliser le point de terminaison GET /api/my-account/sessions.

remarque:

La portée UserScope.Sessions est requise pour accéder à ce point de terminaison.
Le champ Sessions dans les paramètres du centre de compte doit être défini sur ReadOnly ou Edit.

curl https://[tenant-id].logto.app/api/my-account/sessions \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Révoquer une session par ID de session

Pour révoquer une session spécifique, utilisez le point de terminaison DELETE /api/my-account/sessions/{sessionId}.

remarque:

La portée UserScope.Sessions est requise pour accéder à ce point de terminaison.
Le champ Sessions dans les paramètres du centre de compte doit être défini sur Edit.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Paramètres de requête optionnels :

revokeGrantsTarget : Spécifiez éventuellement la cible des grants à révoquer avec la session. Valeurs possibles :
- all : Révoquer tous les grants associés à la session.
- firstParty : Révoquer uniquement les grants d'application de première partie associés à la session. (Recommandé pour la plupart des cas d'utilisation, car cela révoque l'accès pour votre propre application tout en conservant les grants d'application tierce intacts, offrant une meilleure expérience utilisateur.)
- non spécifié : Le comportement par défaut révoque les grants qui n'ont pas de portée offline_access, ce qui signifie généralement révoquer les grants non liés aux jetons de rafraîchissement pour la session.

Gérer les applications autorisées par l'utilisateur (grants)

Utilisez les APIs des applications autorisées par l'utilisateur (grants) lorsque les utilisateurs ont besoin de revoir et de révoquer les applications autorisées depuis leur page de paramètres de compte.

remarque:

Les APIs de grant d'application partagent le même modèle de permission que les APIs de session.
La portée UserScope.Sessions est requise.
Le champ Sessions dans les paramètres du centre de compte doit être activé :
- ReadOnly ou Edit pour lister les grants.
- Edit pour révoquer les grants.

Lister les grants d'application actifs

Pour lister les grants d'application actifs de l'utilisateur actuel, utilisez le point de terminaison GET /api/my-account/grants.

curl https://[tenant-id].logto.app/api/my-account/grants \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Paramètre de requête optionnel :

appType=firstParty : Retourner uniquement les grants d'application de première partie.
appType=thirdParty : Retourner uniquement les grants d'application tierce.
Omettre appType : Retourner tous les grants actifs.

curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Révoquer un grant d'application par ID de grant

Pour révoquer un grant d'application spécifique, utilisez le point de terminaison DELETE /api/my-account/grants/{grantId}.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Lorsqu'un grant est révoqué, les jetons d’accès (Access tokens) opaques et les jetons de rafraîchissement (Refresh tokens) précédemment émis pour ce grant sont invalidés.

Qu'est-ce que Logto Account API​

Comment activer l'Account API​

Comment accéder à l'Account API​

Récupérer un jeton d’accès​

Accéder à l'Account API en utilisant le jeton d’accès​

Gérer les informations de compte de base​

Récupérer les informations de compte utilisateur​

Mettre à jour les informations de compte de base​

Gérer les identifiants et autres informations sensibles​

Obtenir un ID d'enregistrement de vérification​

Vérifier le mot de passe de l'utilisateur​

Vérifier en envoyant un code de vérification à l'e-mail ou au téléphone de l'utilisateur​

Envoyer une requête avec l'ID d'enregistrement de vérification​

Mettre à jour le mot de passe de l'utilisateur​

Mettre à jour ou lier un nouvel e-mail​

Supprimer l'e-mail de l'utilisateur​

Gérer le téléphone​

Lier une nouvelle connexion sociale​

Supprimer une connexion sociale​

Lier une nouvelle clé de passe WebAuthn​

Gérer les clés de passe WebAuthn existantes​

Lier un nouveau TOTP​

Gérer les codes de secours​

Gérer les sessions utilisateur​

Gérer les applications autorisées par l'utilisateur (grants)​

Qu'est-ce que Logto Account API

Comment activer l'Account API

Comment accéder à l'Account API

Récupérer un jeton d’accès

Accéder à l'Account API en utilisant le jeton d’accès

Gérer les informations de compte de base

Récupérer les informations de compte utilisateur

Mettre à jour les informations de compte de base

Gérer les identifiants et autres informations sensibles

Obtenir un ID d'enregistrement de vérification

Vérifier le mot de passe de l'utilisateur

Vérifier en envoyant un code de vérification à l'e-mail ou au téléphone de l'utilisateur

Envoyer une requête avec l'ID d'enregistrement de vérification

Mettre à jour le mot de passe de l'utilisateur

Mettre à jour ou lier un nouvel e-mail

Supprimer l'e-mail de l'utilisateur

Gérer le téléphone

Lier une nouvelle connexion sociale

Supprimer une connexion sociale

Lier une nouvelle clé de passe WebAuthn

Gérer les clés de passe WebAuthn existantes

Lier un nouveau TOTP

Gérer les codes de secours

Gérer les sessions utilisateur

Gérer les applications autorisées par l'utilisateur (grants)