Automatizar o gerenciamento de tenants

Você pode gerenciar tenants do Logto Cloud programaticamente, incluindo criar tenants e continuar a configuração sem precisar acessar o Console.

Isso é útil quando você precisa provisionar tenants a partir do seu próprio fluxo de onboarding, plataforma interna, agente de IA ou automação de integração.

O fluxo de automação é:

1. Use um Token de Acesso Pessoal (PAT) do Logto Cloud para chamar a API do Logto Cloud.
2. Crie um tenant com POST /api/tenants.
3. Leia as credenciais padrão do aplicativo Máquina para máquina (M2M) da resposta de criação.
4. Use o aplicativo M2M padrão para obter um token de acesso da Management API para o novo tenant.
5. Chame a Management API do novo tenant para continuar o provisionamento de aplicativos, usuários, papéis, recursos, organizações e outras configurações.

Criar um PAT

Crie um token de acesso pessoal (PAT) para sua conta Logto Cloud:

1. No Console do Logto Cloud, clique no seu avatar no canto superior direito e selecione Perfil.
2. Abra a página Segurança.
3. Em Tokens de acesso pessoal, clique em Criar novo token.
4. Insira um nome e escolha uma expiração de até 365 dias, depois confirme.

O token é exibido apenas uma vez, logo após sua criação. Copie-o e armazene-o em um local seguro, como um gerenciador de segredos. Você não poderá vê-lo novamente.

Recomendamos uma expiração de 90 dias e a rotação do token antes que ele expire. Você pode renomear ou revogar um token na mesma página.

Revogar um token leva efeito em cerca de um minuto.

Um PAT pode chamar as rotas da Cloud API que exigem o escopo create:tenant ou manage:tenant:self:

• GET /api/me/regions para listar as regiões disponíveis para sua conta.
• POST /api/tenants para criar um tenant.
• GET /api/tenants para listar seus tenants, e PATCH ou DELETE /api/tenants/{tenantId} para renomear ou excluir um.
• POST /api/tenants/{tenantId}/subscription e outros endpoints sob /api/tenants/{tenantId} para gerenciar o plano, faturas e logs de e-mail de um tenant.

Rotas que exigem o escopo manage:account:self, como cobrança, licenças e Console SSO, precisam de uma sessão interativa no Console e não podem ser chamadas com um PAT.

Antes de começar

Prepare os seguintes valores:

Variável	Descrição
CLOUD_API_ENDPOINT	O endpoint da API do Logto Cloud. Para Logto Cloud, use https://cloud.logto.io.
LOGTO_CLOUD_PAT	Um PAT para sua conta Logto Cloud.
TENANT_NAME	O nome de exibição do tenant a ser criado.
TENANT_TAG	O tipo do tenant. Use development ou production.
REGION_NAME	O identificador da região para o tenant.

Defina-os como variáveis de ambiente:

export CLOUD_API_ENDPOINT="https://cloud.logto.io"
export LOGTO_CLOUD_PAT="<logto-cloud-pat>"
export TENANT_NAME="Meu tenant automatizado"
export TENANT_TAG="development"
export REGION_NAME="<region-name>"

Obter regiões disponíveis

Antes de criar um tenant, busque as regiões disponíveis para sua conta Logto Cloud:

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

A resposta contém as regiões disponíveis. Use o valor de name como REGION_NAME ao criar o tenant.

Exemplo de resposta:

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

Criar um tenant

Chame POST /api/tenants com o PAT do 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"'"
  }'

A resposta inclui o tenant criado e um aplicativo M2M padrão. O aplicativo M2M é criado no novo tenant e tem acesso à Management API do tenant.

Exemplo de resposta:

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

Salve os valores necessários para o próximo passo:

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

dica:

Um tenant criado com tag: "production" começa no plano Free. Para colocá-lo no plano Pro a partir do mesmo script, veja Assinar um tenant no plano Pro. Um tenant de desenvolvimento, como o deste exemplo, não pode ser assinado via API.

Obter um token de acesso da Management API para o novo tenant

Use as credenciais do aplicativo M2M padrão para solicitar um token de acesso do novo tenant:

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"

Exemplo de resposta:

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

Salve o token de acesso:

export MANAGEMENT_API_ACCESS_TOKEN="<response.access_token>"

Continue o provisionamento do novo tenant

Use o token de acesso da Management API para chamar a Management API do novo tenant.

Por exemplo, listar aplicativos:

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

Ou criar um aplicativo:

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

Neste ponto, sua automação pode continuar com qualquer operação da Management API, como criar usuários, aplicativos, recursos de API, papéis, organizações, conectores ou configurações da experiência de login.

Exemplo de automação completa

O exemplo Node.js a seguir cria um tenant, troca as credenciais M2M padrão retornadas por um token de acesso da Management API e lista os aplicativos no novo tenant:

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

const createTenantResponse = await fetch(`${cloudApiEndpoint}/api/tenants`, {
  method: 'POST',
  headers: {
    authorization: `Bearer ${logtoCloudPat}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Meu tenant automatizado',
    tag: 'development',
    regionName: 'EU',
  }),
});

if (!createTenantResponse.ok) {
  throw new Error(`Falha ao criar tenant: ${await createTenantResponse.text()}`);
}

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

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(`Falha ao obter token da Management API: ${await tokenResponse.text()}`);
}

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

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

if (!applicationsResponse.ok) {
  throw new Error(`Falha ao listar aplicativos: ${await applicationsResponse.text()}`);
}

const applications = await applicationsResponse.json();

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

Recursos relacionados

• Assinar um tenant no plano Pro
• Token de acesso pessoal
• Interagir com a Management API
• Guia rápido de Máquina para máquina