Skip to main content

Create organization

Imagine you’re building a multi-tenant app (e.g., a multi-tenant SaaS app) that serves many customers, and each customer owns a dedicated tenant.

Organizations are typically created when:

  1. New customers sign up and create both an account and a tenant for their business.
  2. Existing users can create a new organization from within the app.
New account creates organization Existing user creates organization

Implement organization creation​

There are two ways to create organizations for your app.

Create via Logto Console​

Manually create organizations in the Logto Console UI. Go to Console > Organizations to create organizations, assign members and roles, and customize the organization sign‑in experience.

Create an organization template to batch‑create similar organizations that share the same roles and permissions.

Create via Logto Management API​

The console is great for manual setup, but most apps let end users self‑serve—create and manage organizations directly in your app. To do that, implement these features with the Logto Management API.

note:

If you’re new to the Logto Management API or haven't read the basic intro of using Logto Management API for organization experience, read these first:

Set up your app service with the Logto Management API

Management APIInteract with Management API

Assume your backend is connected to the Logto Management API via the machine‑to‑machine (M2M) mechanism, and you’ve obtained an M2M access token.

Create an organization with Management API (API references):

curl \
 -X POST https://[tenant_id].logto.app/api/organizations \
 -H "Authorization: Bearer $M2M_ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"tenantId":"string","name":"string","description":"string","customData":{},"isMfaRequired":false,"branding":{"logoUrl":"string","darkLogoUrl":"string","favicon":"string","darkFavicon":"string"},"createdAt":1234567890}'

Then add the user as a member of the organization (API reference):

curl \
 -X POST https://[tenant_id].logto.app/api/organizations/{id}/users \
 -H "Authorization: Bearer $M2M_ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"userIds":["string"]}'

Optionally, assign specific organization roles to the user (API reference).

Check the full API specs for more details.

Wrap these calls in your own API layer. When users perform the “create organization” action in your app, validate the request by checking their permissions, then call the Logto Management API to complete the operation.

Validate the organization token in user requests​

In your app, when users perform actions in the context of an organization, they must use an organization token instead of a regular access token. The organization token is a JWT that contains organization permissions. Like any access token, you can decode the claims and verify the "scope" claim to enforce permissions.

See Authorization for more on authorization scenarios and how to validate organization tokens.