Aller au contenu principal

Paramètres du compte par Account API

Qu'est-ce que Logto Account API​

L'Account API de Logto est un ensemble complet d'API qui offre 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 leur propre profil de compte sans nécessiter le relais du Management API.
  • Gestion du profil utilisateur et des identités : 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'email, le téléphone et le mot de passe, ainsi que de gérer les connexions sociales. Le support pour l'authentification multi-facteurs (MFA) et l'authentification unique (SSO) arrive bientôt.
  • Contrôle d'accès global : L'administrateur a un contrôle total et global sur les paramètres d'accès, et peut personnaliser chaque champ.
  • Autorisation transparente : L'autorisation est plus facile que jamais ! Utilisez simplement client.getAccessToken() pour obtenir un jeton d’accès (Opaque token) pour OP (Logto), et attachez-le à l'en-tête d'Autorisation comme Bearer <access_token>.

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

Voici quelques utilisations fréquentes :

  • 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'email, le téléphone et les connexions sociales

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

Comment activer l'Account API​

Par défaut, l'Account API est désactivée. Pour l'activer, vous devez utiliser le Management API pour mettre à jour les paramètres globaux.

Le point de terminaison de l'API /api/account-center peut être utilisé pour récupérer et mettre à jour les paramètres du centre de compte, vous pouvez l'utiliser pour activer ou désactiver l'Account API, et personnaliser les champs.

Exemple de requête :

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token for Logto Management API>' \
  -H 'content-type: application/json' \
  --data-raw '{"enabled":true,"fields":{"username":"Edit"}}'

Le champ enabled est utilisé pour activer ou désactiver l'Account API, et le champ fields est utilisé pour personnaliser les champs, la valeur peut être Off, Edit, ReadOnly. La valeur par défaut est Off. La liste des champs :

  • name : Le champ du nom.
  • avatar : Le champ de l'avatar.
  • profile : Le champ du profil, y compris ses sous-champs.
  • username : Le champ du nom d'utilisateur.
  • email : Le champ de l'email.
  • phone : Le champ du téléphone.
  • password : Le champ du mot de passe, lors de l'obtention, il retournera true si l'utilisateur a défini un mot de passe, sinon false.
  • social : Connexions sociales.

En savoir plus sur les détails de l'API dans Logto Management API Reference.

Comment accéder à l'Account API​

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 (Opaque token) 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 placer le jeton d’accès dans le champ Authorization des en-têtes HTTP avec le format Bearer (Bearer YOUR_TOKEN) lorsque vous interagissez avec l'Account API.

Un exemple pour obtenir les informations du compte utilisateur :

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

Gérer les informations de base du compte​

Récupérer les informations du compte utilisateur​

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 base du compte​

Les informations de base du compte incluent le nom d'utilisateur, le nom, l'avatar et le profil.

Pour mettre à jour le nom d'utilisateur, le nom et l'avatar, 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 le profil, 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 autre couche d'autorisation pour les opérations impliquant des identifiants et d'autres informations sensibles.

Obtenir un identifiant d'enregistrement de vérification​

Tout d'abord, vous devez obtenir un identifiant d'enregistrement de vérification, cela peut être utilisé pour vérifier l'identité de l'utilisateur lors de la mise à jour des identifiants.

Pour obtenir un identifiant d'enregistrement de vérification, vous pouvez vérifier le mot de passe de l'utilisateur ou envoyer un code de vérification à l'email 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'email ou au téléphone de l'utilisateur​

remarque

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

Prenons l'email comme exemple, demandez un nouveau code de vérification et obtenez l'identifiant 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 PATCH 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'identifiant d'enregistrement de vérification pour mettre à jour l'identifiant de l'utilisateur.

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

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

Mettre à jour ou lier un nouvel email​

remarque

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

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

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'email, utilisez-le pour vérifier l'email.

curl -X PATCH 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 mettre à jour l'email de l'utilisateur, définissez le verificationId dans le corps de la requête comme newIdentifierVerificationRecordId.

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

Supprimer l'email de l'utilisateur​

Pour supprimer l'email 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'email, 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.

Lier une nouvelle connexion sociale​

Pour lier une nouvelle connexion sociale, vous devez d'abord demander une URL d'autorisation :

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 en JSON comme valeur du champ connectorData.

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

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

Supprimer une connexion sociale​

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>'