Organization is a concept that brings together multiple identities (mostly users). Logto supports multiple organizations, and each organization can have multiple users. Every organization shares the same set (organization template) of roles and permissions. Each user can have different roles in different organizations. See [🏢 Organizations (Multi-tenancy)](https://docs.logto.io/docs/recipes/organizations/) to get started with organizations and organization template.
openapi: 3.0.1
info:
title: Logto API references Account center Organizations API
description: 'API references for Logto services.
Note: The documentation is for Logto Cloud. If you are using Logto OSS, please refer to the response of `/api/swagger.json` endpoint on your Logto instance.'
version: Cloud
servers:
- url: https://[tenant_id].logto.app/
description: Logto endpoint address.
security:
- OAuth2:
- all
tags:
- name: Organizations
description: 'Organization is a concept that brings together multiple identities (mostly users). Logto supports multiple organizations, and each organization can have multiple users.
Every organization shares the same set (organization template) of roles and permissions. Each user can have different roles in different organizations. See [🏢 Organizations (Multi-tenancy)](https://docs.logto.io/docs/recipes/organizations/) to get started with organizations and organization template.'
paths:
/api/organizations:
post:
operationId: CreateOrganization
tags:
- Organizations
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
tenantId:
type: string
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description: The name of the organization.
description:
type: string
maxLength: 256
nullable: true
description: The description of the organization.
customData:
type: object
description: arbitrary
isMfaRequired:
type: boolean
color:
type: object
properties:
primaryColor:
type: string
format: regex
pattern: /^#[\da-f]{3}([\da-f]{3})?$/i
isDarkModeEnabled:
type: boolean
darkPrimaryColor:
type: string
format: regex
pattern: /^#[\da-f]{3}([\da-f]{3})?$/i
branding:
type: object
properties:
logoUrl:
type: string
format: url
darkLogoUrl:
type: string
format: url
favicon:
type: string
format: url
darkFavicon:
type: string
format: url
customCss:
type: string
nullable: true
createdAt:
type: number
responses:
'201':
description: The organization was created successfully.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- name
- description
- customData
- isMfaRequired
- color
- branding
- customCss
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description:
type: string
maxLength: 256
nullable: true
customData:
type: object
description: arbitrary
isMfaRequired:
type: boolean
color:
type: object
properties:
primaryColor:
type: string
format: regex
pattern: /^#[\da-f]{3}([\da-f]{3})?$/i
isDarkModeEnabled:
type: boolean
darkPrimaryColor:
type: string
format: regex
pattern: /^#[\da-f]{3}([\da-f]{3})?$/i
branding:
type: object
properties:
logoUrl:
type: string
format: url
darkLogoUrl:
type: string
format: url
favicon:
type: string
format: url
darkFavicon:
type: string
format: url
customCss:
type: string
nullable: true
createdAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Create an organization
description: Create a new organization with the given data.
get:
operationId: ListOrganizations
tags:
- Organizations
parameters:
- name: q
in: query
required: false
schema:
type: string
description: 'The query to filter organizations. It can be a partial ID or name.
If not provided, all organizations will be returned.'
- name: showFeatured
in: query
required: false
schema:
type: string
description: 'Whether to show featured users in the organization. Featured users are randomly selected from the organization members.
If not provided, `featuredUsers` will not be included in the response.'
- name: page
in: query
description: Page number (starts from 1).
required: false
schema:
type: integer
minimum: 1
default: 1
- name: page_size
in: query
description: Entries per page.
required: false
schema:
type: integer
minimum: 1
default: 20
responses:
'200':
description: A list of organizations.
content:
application/json:
schema:
type: array
items:
type: object
required:
- tenantId
- id
- name
- description
- customData
- isMfaRequired
- color
- branding
- customCss
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description:
type: string
maxLength: 256
nullable: true
customData:
type: object
description: arbitrary
isMfaRequired:
type: boolean
color:
type: object
properties:
primaryColor:
type: string
format: regex
pattern: /^#[\da-f]{3}([\da-f]{3})?$/i
isDarkModeEnabled:
type: boolean
darkPrimaryColor:
type: string
format: regex
pattern: /^#[\da-f]{3}([\da-f]{3})?$/i
branding:
type: object
properties:
logoUrl:
type: string
format: url
darkLogoUrl:
type: string
format: url
favicon:
type: string
format: url
darkFavicon:
type: string
format: url
customCss:
type: string
nullable: true
createdAt:
type: number
usersCount:
type: number
featuredUsers:
type: array
items:
type: object
required:
- id
- avatar
- name
properties:
id:
type: string
minLength: 1
maxLength: 12
avatar:
type: string
maxLength: 2048
nullable: true
name:
type: string
maxLength: 128
nullable: true
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Get organizations
description: Get organizations that match the given query with pagination.
/api/organizations/{id}:
get:
operationId: GetOrganization
tags:
- Organizations
parameters:
- $ref: '#/components/parameters/organizationId-root'
responses:
'200':
description: Details of the organization.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- name
- description
- customData
- isMfaRequired
- color
- branding
- customCss
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description:
type: string
maxLength: 256
nullable: true
customData:
type: object
description: arbitrary
isMfaRequired:
type: boolean
color:
type: object
properties:
primaryColor:
type: string
format: regex
pattern: /^#[\da-f]{3}([\da-f]{3})?$/i
isDarkModeEnabled:
type: boolean
darkPrimaryColor:
type: string
format: regex
pattern: /^#[\da-f]{3}([\da-f]{3})?$/i
branding:
type: object
properties:
logoUrl:
type: string
format: url
darkLogoUrl:
type: string
format: url
favicon:
type: string
format: url
darkFavicon:
type: string
format: url
customCss:
type: string
nullable: true
createdAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Get organization
description: Get organization details by ID.
patch:
operationId: UpdateOrganization
tags:
- Organizations
parameters:
- $ref: '#/components/parameters/organizationId-root'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description: The updated name of the organization.
description:
type: string
maxLength: 256
nullable: true
description: The updated description of the organization.
customData:
type: object
description: arbitrary
isMfaRequired:
type: boolean
color:
type: object
properties:
primaryColor:
type: string
format: regex
pattern: /^#[\da-f]{3}([\da-f]{3})?$/i
isDarkModeEnabled:
type: boolean
darkPrimaryColor:
type: string
format: regex
pattern: /^#[\da-f]{3}([\da-f]{3})?$/i
branding:
type: object
properties:
logoUrl:
type: string
format: url
darkLogoUrl:
type: string
format: url
favicon:
type: string
format: url
darkFavicon:
type: string
format: url
customCss:
type: string
nullable: true
createdAt:
type: number
responses:
'200':
description: The organization was updated successfully.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- name
- description
- customData
- isMfaRequired
- color
- branding
- customCss
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description:
type: string
maxLength: 256
nullable: true
customData:
type: object
description: arbitrary
isMfaRequired:
type: boolean
color:
type: object
properties:
primaryColor:
type: string
format: regex
pattern: /^#[\da-f]{3}([\da-f]{3})?$/i
isDarkModeEnabled:
type: boolean
darkPrimaryColor:
type: string
format: regex
pattern: /^#[\da-f]{3}([\da-f]{3})?$/i
branding:
type: object
properties:
logoUrl:
type: string
format: url
darkLogoUrl:
type: string
format: url
favicon:
type: string
format: url
darkFavicon:
type: string
format: url
customCss:
type: string
nullable: true
createdAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Update organization
description: Update organization details by ID with the given data.
delete:
operationId: DeleteOrganization
tags:
- Organizations
parameters:
- $ref: '#/components/parameters/organizationId-root'
responses:
'204':
description: The organization was deleted successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Delete organization
description: Delete organization by ID.
/api/organizations/{id}/users:
get:
operationId: ListOrganizationUsers
tags:
- Organizations
parameters:
- $ref: '#/components/parameters/organizationId-root'
- name: q
in: query
required: false
schema:
type: string
description: 'The query to filter users. It will match multiple fields of users, including ID, name, username, email, and phone number.
If not provided, all users will be returned.'
- name: page
in: query
description: Page number (starts from 1).
required: false
schema:
type: integer
minimum: 1
default: 1
- name: page_size
in: query
description: Entries per page.
required: false
schema:
type: integer
minimum: 1
default: 20
responses:
'200':
description: A list of users that are members of the organization.
content:
application/json:
schema:
type: array
items:
type: object
required:
- id
- username
- primaryEmail
- primaryPhone
- name
- avatar
- customData
- identities
- lastSignInAt
- createdAt
- updatedAt
- profile
- applicationId
- isSuspended
- organizationRoles
properties:
id:
type: string
minLength: 1
maxLength: 12
username:
type: string
maxLength: 128
nullable: true
primaryEmail:
type: string
maxLength: 128
nullable: true
primaryPhone:
type: string
maxLength: 128
nullable: true
name:
type: string
maxLength: 128
nullable: true
avatar:
type: string
maxLength: 2048
nullable: true
customData:
type: object
description: arbitrary
identities:
type: object
additionalProperties:
type: object
required:
- userId
properties:
userId:
type: string
details:
type: object
description: arbitrary
lastSignInAt:
type: number
nullable: true
createdAt:
type: number
updatedAt:
type: number
profile:
type: object
properties:
familyName:
type: string
givenName:
type: string
middleName:
type: string
nickname:
type: string
preferredUsername:
type: string
profile:
type: string
website:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
address:
type: object
properties:
formatted:
type: string
streetAddress:
type: string
locality:
type: string
region:
type: string
postalCode:
type: string
country:
type: string
applicationId:
type: string
maxLength: 21
nullable: true
isSuspended:
type: boolean
organizationRoles:
type: array
items:
type: object
required:
- id
- name
properties:
id:
type: string
name:
type: string
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Get organization user members
description: Get users that are members of the specified organization for the given query with pagination.
post:
operationId: AddOrganizationUsers
tags:
- Organizations
parameters:
- $ref: '#/components/parameters/organizationId-root'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- userIds
properties:
userIds:
type: array
items:
type: string
minLength: 1
description: An array of user IDs to be added to the organization. Organization existed users assignment will be ignored.
responses:
'201':
description: Users were added to the organization successfully.
content:
application/json:
schema:
type: object
required:
- userIds
properties:
userIds:
type: array
items:
type: string
minLength: 1
description: An array of user IDs processed from the request. This may include IDs that were already members of the organization.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: At least one of the IDs provided is not valid. For example, the organization ID or user ID does not exist.
summary: Add user members to organization
description: Add users as members to the specified organization with the given user IDs.
put:
operationId: ReplaceOrganizationUsers
tags:
- Organizations
parameters:
- $ref: '#/components/parameters/organizationId-root'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- userIds
properties:
userIds:
type: array
items:
type: string
minLength: 1
description: An array of user IDs to replace existing users.
responses:
'204':
description: Successfully replaced all users for the organization.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: At least one of the IDs provided is not valid. For example, the organization ID or user ID does not exist.
summary: Replace organization user members
description: Replace all user members for the specified organization with the given users. This effectively removing all existing user memberships in the organization and adding the new users as members.
/api/organizations/{id}/users/{userId}:
delete:
operationId: DeleteOrganizationUser
tags:
- Organizations
parameters:
- $ref: '#/components/parameters/organizationId-root'
- $ref: '#/components/parameters/userId'
responses:
'204':
description: The user was removed from the organization members successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The user is not a member of the organization.
'422':
description: Unprocessable Content
summary: Remove user member from organization
description: Remove a user's membership from the specified organization.
/api/organizations/{id}/users/roles:
post:
operationId: AssignOrganizationRolesToUsers
tags:
- Organizations
parameters:
- $ref: '#/components/parameters/organizationId-root'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- userIds
- organizationRoleIds
properties:
userIds:
type: array
items:
type: string
minLength: 1
description: An array of user IDs to assign roles.
organizationRoleIds:
type: array
items:
type: string
minLength: 1
description: An array of organization role IDs to assign. User existed roles assignment will be ignored.
responses:
'201':
description: Roles were assigned to organization users successfully.
content:
application/json: {}
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: At least one of the IDs provided is not valid. For example, the organization ID, user ID, or organization role ID does not exist; the user is not a member of the organization; or the role type is not assignable to the user.
summary: Assign roles to organization user members
description: Assign roles to user members of the specified organization.
/api/organizations/{id}/users/{userId}/roles:
get:
operationId: ListOrganizationUserRoles
tags:
- Organizations
parameters:
- $ref: '#/components/parameters/organizationId-root'
- $ref: '#/components/parameters/userId'
- name: page
in: query
description: Page number (starts from 1).
required: false
schema:
type: integer
minimum: 1
default: 1
- name: page_size
in: query
description: Entries per page.
required: false
schema:
type: integer
minimum: 1
default: 20
responses:
'200':
description: A list of roles assigned to the user.
content:
application/json:
schema:
type: array
items:
type: object
required:
- tenantId
- id
- name
- description
- type
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description:
type: string
maxLength: 256
nullable: true
type:
type: string
enum:
- User
- MachineToMachine
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: The user is not a member of the organization.
summary: Get roles for a user in an organization
description: Get roles assigned to a user in the specified organization with pagination.
post:
operationId: AssignOrganizationRolesToUser
tags:
- Organizations
parameters:
- $ref: '#/components/parameters/organizationId-root'
- $ref: '#/components/parameters/userId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
organizationRoleIds:
type: array
items:
type: string
minLength: 1
description: An array of organization role IDs to assign to the user. User existed roles assignment will be ignored.
organizationRoleNames:
type: array
items:
type: string
minLength: 1
description:
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/logto/refs/heads/main/openapi/logto-organizations-api-openapi.yml