Automatiser la gestion des locataires

Vous pouvez gérer les locataires Logto Cloud de manière programmatique, y compris créer des locataires et poursuivre la configuration sans passer par la Console.

Ceci est utile lorsque vous devez approvisionner des locataires depuis votre propre parcours d'intégration, une plateforme interne, un agent IA ou une automatisation d'intégration.

Le flux d'automatisation est le suivant :

1. Utilisez un Jeton d’accès personnel Logto Cloud (PAT) pour appeler l’API Logto Cloud.
2. Créez un locataire avec POST /api/tenants.
3. Lisez les identifiants de l’application Machine à machine (M2M) par défaut dans la réponse de création.
4. Utilisez l’application M2M par défaut pour obtenir un jeton d’accès Management API pour le nouveau locataire.
5. Appelez la Management API du nouveau locataire pour continuer l’approvisionnement des applications, utilisateurs, rôles, ressources, organisations et autres paramètres.

Créer un PAT

Créez un jeton d’accès personnel (PAT) pour votre compte Logto Cloud :

1. Dans la Console Logto Cloud, cliquez sur votre avatar en haut à droite et sélectionnez Profil.
2. Ouvrez la page Sécurité.
3. Dans Jetons d’accès personnels, cliquez sur Créer un nouveau jeton.
4. Saisissez un nom et choisissez une expiration jusqu’à 365 jours, puis confirmez.

Le jeton n’est affiché qu’une seule fois, juste après sa création. Copiez-le et stockez-le dans un endroit sûr, comme un gestionnaire de secrets. Vous ne pourrez plus le voir par la suite.

Nous recommandons une expiration de 90 jours et de faire tourner le jeton avant son expiration. Vous pouvez renommer ou révoquer un jeton sur la même page.

La révocation d’un jeton prend effet en environ une minute.

Un PAT peut appeler les routes de l’API Cloud qui nécessitent la portée create:tenant ou manage:tenant:self :

• GET /api/me/regions pour lister les régions disponibles pour votre compte.
• POST /api/tenants pour créer un locataire.
• GET /api/tenants pour lister vos locataires, et PATCH ou DELETE /api/tenants/{tenantId} pour renommer ou supprimer un locataire.
• POST /api/tenants/{tenantId}/subscription et les autres points de terminaison sous /api/tenants/{tenantId} pour gérer le plan, les factures et les journaux d’e-mails d’un locataire.

Les routes qui nécessitent la portée manage:account:self, telles que la facturation, les licences et la Console SSO, nécessitent une session Console interactive et ne peuvent pas être appelées avec un PAT.

Avant de commencer

Préparez les valeurs suivantes :

Variable	Description
CLOUD_API_ENDPOINT	Le point de terminaison de l’API Logto Cloud. Pour Logto Cloud, utilisez https://cloud.logto.io.
LOGTO_CLOUD_PAT	Un PAT pour votre compte Logto Cloud.
TENANT_NAME	Le nom d’affichage du locataire à créer.
TENANT_TAG	Le type de locataire. Utilisez development ou production.
REGION_NAME	L’identifiant de la région pour le locataire.

Définissez-les comme variables d’environnement :

export CLOUD_API_ENDPOINT="https://cloud.logto.io"
export LOGTO_CLOUD_PAT="<logto-cloud-pat>"
export TENANT_NAME="Mon locataire automatisé"
export TENANT_TAG="development"
export REGION_NAME="<region-name>"

Obtenir les régions disponibles

Avant de créer un locataire, récupérez les régions disponibles pour votre compte Logto Cloud :

curl "$CLOUD_API_ENDPOINT/api/me/regions" \
  -H "Authorization: Bearer $LOGTO_CLOUD_PAT"

La réponse contient les régions disponibles. Utilisez la valeur name comme REGION_NAME lors de la création du locataire.

Exemple de réponse :

{
  "regions": [
    {
      "name": "EU",
      "displayName": "Europe"
    },
    {
      "name": "US",
      "displayName": "United States"
    }
  ]
}

Créer un locataire

Appelez POST /api/tenants avec le PAT Logto Cloud :

curl "$CLOUD_API_ENDPOINT/api/tenants" \
  -X POST \
  -H "Authorization: Bearer $LOGTO_CLOUD_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "'"$TENANT_NAME"'",
    "tag": "'"$TENANT_TAG"'",
    "regionName": "'"$REGION_NAME"'"
  }'

La réponse inclut le locataire créé et une application M2M par défaut. L’application M2M est créée dans le nouveau locataire et a accès à la Management API du locataire.

Exemple de réponse :

{
  "id": "new-tenant-id",
  "name": "Mon locataire automatisé",
  "tag": "development",
  "indicator": "https://new-tenant-id.logto.app",
  "regionName": "EU",
  "defaultApplication": {
    "id": "default-m2m-app-id",
    "secret": "default-m2m-app-secret"
  }
}

Enregistrez les valeurs dont vous avez besoin pour l’étape suivante :

export TENANT_ID="<response.id>"
export TENANT_ENDPOINT="<response.indicator>"
export DEFAULT_M2M_APP_ID="<response.defaultApplication.id>"
export DEFAULT_M2M_APP_SECRET="<response.defaultApplication.secret>"

astuce:

Un locataire créé avec tag: "production" commence sur le plan Free. Pour le passer au plan Pro depuis le même script, voir Abonner un locataire au plan Pro. Un locataire de développement, comme dans cet exemple, ne peut pas être abonné via l’API.

Obtenir un jeton d’accès Management API pour le nouveau locataire

Utilisez les identifiants de l’application M2M par défaut pour demander un jeton d’accès au nouveau locataire :

curl "$TENANT_ENDPOINT/oidc/token" \
  -X POST \
  -u "$DEFAULT_M2M_APP_ID:$DEFAULT_M2M_APP_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "resource=$TENANT_ENDPOINT/api" \
  -d "scope=all"

Exemple de réponse :

{
  "access_token": "eyJ...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "all"
}

Enregistrez le jeton d’accès :

export MANAGEMENT_API_ACCESS_TOKEN="<response.access_token>"

Continuer l’approvisionnement du nouveau locataire

Utilisez le jeton d’accès Management API pour appeler la Management API du nouveau locataire.

Par exemple, lister les applications :

curl "$TENANT_ENDPOINT/api/applications" \
  -H "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN"

Ou créer une application :

curl "$TENANT_ENDPOINT/api/applications" \
  -X POST \
  -H "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mon application web",
    "type": "SPA",
    "oidcClientMetadata": {
      "redirectUris": ["https://example.com/callback"],
      "postLogoutRedirectUris": ["https://example.com"]
    }
  }'

À ce stade, votre automatisation peut continuer avec n’importe quelle opération Management API, comme la création d’utilisateurs, d’applications, de ressources API, de rôles, d’organisations, de connecteurs ou de paramètres d’expérience de connexion.

Exemple d’automatisation complète

L’exemple Node.js suivant crée un locataire, échange les identifiants M2M par défaut retournés contre un jeton d’accès Management API, et liste les applications du nouveau locataire :

const cloudApiEndpoint = 'https://cloud.logto.io';
const logtoCloudPat = process.env.LOGTO_CLOUD_PAT;

// Créer un locataire
const createTenantResponse = await fetch(`${cloudApiEndpoint}/api/tenants`, {
  method: 'POST',
  headers: {
    authorization: `Bearer ${logtoCloudPat}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Mon locataire automatisé',
    tag: 'development',
    regionName: 'EU',
  }),
});

if (!createTenantResponse.ok) {
  throw new Error(`Échec de la création du locataire : ${await createTenantResponse.text()}`);
}

const tenant = await createTenantResponse.json();
const tenantEndpoint = tenant.indicator;
const { id: appId, secret: appSecret } = tenant.defaultApplication;

// Obtenir un jeton d’accès Management API
const tokenResponse = await fetch(`${tenantEndpoint}/oidc/token`, {
  method: 'POST',
  headers: {
    authorization: `Basic ${Buffer.from(`${appId}:${appSecret}`).toString('base64')}`,
    'content-type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    resource: `${tenantEndpoint}/api`,
    scope: 'all',
  }),
});

if (!tokenResponse.ok) {
  throw new Error(`Échec de l’obtention du jeton Management API : ${await tokenResponse.text()}`);
}

const { access_token: managementApiAccessToken } = await tokenResponse.json();

// Lister les applications
const applicationsResponse = await fetch(`${tenantEndpoint}/api/applications`, {
  headers: {
    authorization: `Bearer ${managementApiAccessToken}`,
  },
});

if (!applicationsResponse.ok) {
  throw new Error(`Échec de la liste des applications : ${await applicationsResponse.text()}`);
}

const applications = await applicationsResponse.json();

console.log({ tenantId: tenant.id, applications });

Ressources associées

• Abonner un locataire au plan Pro
• Jeton d’accès personnel
• Interagir avec Management API
• Démarrage rapide Machine à machine