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 commeBearer <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 retourneratrue
si l'utilisateur a défini un mot de passe, sinonfalse
.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
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
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
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>'