Aller au contenu principal

Paramètres du compte via l’Account API

Qu’est-ce que l’Account API de Logto​

L’Account API de Logto est un ensemble complet d’API qui donne aux utilisateurs finaux un accès direct à l’API sans avoir besoin de passer par la Management API. Voici les points clés :

  • Accès direct : L’Account API permet aux utilisateurs finaux d’accéder et de gérer directement leur propre profil de compte sans nécessiter le relais de la Management API.
  • Gestion du profil utilisateur et des identités : Les utilisateurs peuvent gérer entièrement leur profil et leurs 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 disposent d’un contrôle global complet sur les paramètres d’accès et peuvent personnaliser chaque champ.
  • Autorisation transparente : L’autorisation (Authorization) est plus simple que jamais ! Utilisez simplement client.getAccessToken() pour obtenir un jeton d’accès opaque (Jeton d’accès (Access token)) pour OP (Logto), et attachez-le à l’en-tête Authorization sous la forme Bearer <access_token>.
remarque:

Pour garantir que le jeton d’accès (Jeton d’accès (Access token)) dispose des permissions appropriées, assurez-vous d’avoir correctement configuré les portées (Portées (Scopes)) 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 selon vos cas d’usage.
  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
  ],
};

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é à Logto.

Voici quelques cas d’usage 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)

Pour en savoir plus sur les APIs disponibles, veuillez consulter la référence Logto Account API et la référence Logto Verification API.

remarque:

Des APIs Account dédiées pour les paramètres suivants arrivent bientôt : MFA, SSO, Données personnalisées (utilisateur) et suppression de compte. En attendant, vous pouvez implémenter ces fonctionnalités via les Management APIs de Logto. Voir Paramètres du compte via la Management API pour plus de détails.

Comment activer l’Account API​

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

Le point de terminaison /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 permet d’activer ou de désactiver l’Account API, et le champ fields permet de personnaliser les champs, la valeur pouvant être Off, Edit, ReadOnly. La valeur par défaut est Off. Liste des champs :

  • name : Le champ nom.
  • avatar : Le champ avatar.
  • profile : Le champ profil, y compris ses sous-champs.
  • username : Le champ nom d’utilisateur.
  • email : Le champ e-mail.
  • phone : Le champ téléphone.
  • password : Le champ mot de passe, lors de la récupération, il retournera true si l’utilisateur a défini un mot de passe, sinon false.
  • social : Connexions sociales.
  • mfa : Facteurs MFA.

En savoir plus sur les détails de l’API dans la référence Logto Management API.

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 (Jeton d’accès (Access token)). Ce jeton est un jeton opaque (Jeton opaque (Opaque token)) qui peut être utilisé pour accéder à l’Account API.

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

Accéder à l’Account API avec le jeton d’accès​

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

Voici 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 sera similaire à :

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

Les champs de la réponse peuvent varier selon les 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 requiert une couche supplémentaire d’autorisation (Autorisation (Authorization)) pour les opérations impliquant des identifiants et autres informations sensibles.

Obtenir un identifiant d’enregistrement de vérification​

Vous devez d’abord obtenir un identifiant d’enregistrement de vérification. Celui-ci 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’e-mail ou au téléphone de l’utilisateur.

Pour en savoir plus sur les vérifications, veuillez consulter Vérification de sécurité via l’Account API.

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 sera similaire à :

{
  "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 le connecteur SMS, et vous assurer que le template UserPermissionValidation est configuré.

Prenons l’e-mail 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 sera similaire à :

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

Après réception du code de vérification, vous pouvez l’utiliser pour mettre à jour le statut de vérification de l’enregistrement.

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 vérification du 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 inclure l’identifiant d’enregistrement de vérification dans l’en-tête de la requête avec le champ logto-verification-id.

remarque:

Pour utiliser cette méthode, vous devez configurer le connecteur e-mail et vous assurer que le template 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 par 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 vérification du code, vous pouvez maintenant mettre à jour l’e-mail de l’utilisateur, en définissant 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’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 template BindNewIdentifier est configuré.

De manière 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 utiliser 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 :

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 callback.
  • state : L’état à retourner après que l’utilisateur a autorisé l’application, il s’agit d’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 callback à l’redirectUri avec le paramètre state. Vous pouvez alors 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 la donnée retournée par le connecteur social après que l’utilisateur a autorisé l’application, vous devez analyser et récupérer les paramètres de requête depuis l’redirectUri sur votre page de callback, et les encapsuler en JSON comme valeur du champ connectorData.

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

curl -X POST 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>'
remarque:

N’oubliez pas d’activer MFA et WebAuthn au préalable.

remarque:

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

Étape 0 : Ajoutez l’origine de votre application front-end aux origines associées.

Une passkey dans le navigateur est liée à un nom d’hôte spécifique (RP ID), et seule l’origine du RP ID peut être utilisée pour enregistrer ou vérifier une passkey. Cependant, votre application front-end qui envoie la requête à l’Account API n’est pas la même que la page de connexion Logto, vous devez donc ajouter l’origine de votre application front-end à la liste des origines associées. Cela permettra à votre application front-end d’enregistrer et de vérifier une passkey sous d’autres RP ID.

Par défaut, Logto définit le RP ID sur le domaine du tenant, par exemple, si votre domaine de tenant est https://example.logto.app, le RP ID sera example.logto.app. Si vous utilisez un domaine personnalisé, le RP ID sera le domaine personnalisé, par exemple, si votre domaine personnalisé est https://auth.example.com, le RP ID sera auth.example.com.

Ajoutons maintenant l’origine de votre application front-end aux origines associées, par exemple, si l’origine de votre application front-end est https://account.example.com :

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

Pour en savoir plus sur les origines associées, veuillez consulter la documentation Related Origin Requests.

Étape 1 : demander de nouvelles options d’enregistrement.

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 2 : enregistrer la passkey dans le navigateur local.

Prenons @simplewebauthn/browser comme exemple, vous pouvez utiliser la fonction startRegistration pour enregistrer la passkey 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
});
// Sauvegardez la réponse pour une utilisation ultérieure

Étape 3 : vérifier la passkey.

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’identifiant d’enregistrement de vérification retourné par le serveur à l’étape 1.

Étape 4 : enfin, vous pouvez lier la passkey.

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 identifiant d’enregistrement de vérification valide, obtenu en vérifiant le facteur existant de l’utilisateur, voir la section Obtenir un identifiant d’enregistrement de vérification pour plus de détails.
  • type : le type du facteur MFA, actuellement seul WebAuthn est supporté.
  • newIdentifierVerificationRecordId : l’identifiant d’enregistrement de vérification retourné par le serveur à l’étape 1.

Gérer une passkey WebAuthn existante​

Pour gérer une passkey WebAuthn existante, vous pouvez utiliser le point de terminaison GET /api/my-account/mfa-verifications pour obtenir les passkeys actuelles et 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 sera similaire à :

[
  {
    "id": "...",
    "type": "WebAuthn",
    "name": "...",
    "agent": "...",
    "createdAt": "...",
    "updatedAt": "..."
  }
]
  • id : l’ID de la vérification.
  • type : le type de la vérification, WebAuthn pour une passkey WebAuthn.
  • name : le nom de la passkey, champ optionnel.
  • agent : l’agent utilisateur de la passkey.

Mettre à jour le nom de la passkey :

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 passkey :

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