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: An array of organization role names to assign to the user. User existed roles assignment will be ignored. responses: '201': description: Roles were assigned to the user successfully. content: application/json: schema: type: object required: - organizationRoleIds properties: organizationRoleIds: type: array items: type: string minLength: 1 description: An array of organization role IDs that were assigned to the user, deduplicated and resolved from any provided role names. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The user is not a member of the organization; or at least one of the IDs provided is not valid. For example, the organization ID or organization role ID does not exist; or at least one of the role names provided is not valid. For example, the organization role name does not exist. summary: Assign roles to a user in an organization description: Assign roles to a user in the specified organization with the provided data. put: operationId: ReplaceOrganizationUserRoles 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 update for the user. organizationRoleNames: type: array items: type: string minLength: 1 description: An array of organization role names to update for the user. responses: '204': description: Roles were updated for the user successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The user is not a member of the organization; or at least one of the IDs provided is not valid. For example, the organization ID or organization role ID does not exist; or at least one of the role names provided is not valid. For example, the organization role name does not exist. summary: Update roles for a user in an organization description: Update roles assigned to a user in the specified organization with the provided data. /api/organizations/{id}/users/{userId}/roles/{organizationRoleId}: delete: operationId: DeleteOrganizationUserRole tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - $ref: '#/components/parameters/userId' - $ref: '#/components/parameters/organizationRoleId' responses: '204': description: The role was removed from the user successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Cannot find the record to delete. '422': description: The user is not a member of the organization. summary: Remove a role from a user in an organization description: Remove a role assignment from a user in the specified organization. /api/organizations/{id}/users/{userId}/scopes: get: operationId: ListOrganizationUserScopes tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - $ref: '#/components/parameters/userId' responses: '200': description: A list of scopes assigned to the user. content: application/json: schema: type: array items: type: object required: - tenantId - id - name - description 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 '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The user is not a member of the organization. summary: Get scopes for a user in an organization tailored by the organization roles description: Get scopes assigned to a user in the specified organization tailored by the organization roles. The scopes are derived from the organization roles assigned to the user. /api/organizations/{id}/applications: post: operationId: AddOrganizationApplications tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' requestBody: required: true content: application/json: schema: type: object required: - applicationIds properties: applicationIds: type: array items: type: string minLength: 1 description: The application IDs to add. responses: '201': description: The application was added successfully. content: application/json: {} '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The application could not be added. Some of the applications may not exist. summary: Add organization application description: Add an application to the organization. put: operationId: ReplaceOrganizationApplications tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' requestBody: required: true content: application/json: schema: type: object required: - applicationIds properties: applicationIds: type: array items: type: string minLength: 1 description: An array of application IDs to replace existing applications. responses: '204': description: The applications were replaced successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The applications could not be replaced. Some of the applications may not exist. summary: Replace organization applications description: Replace all applications associated with the organization with the given data. get: operationId: ListOrganizationApplications tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - name: q in: query required: false schema: type: string - 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 applications. content: application/json: schema: type: array items: type: object required: - tenantId - id - name - secret - description - type - oidcClientMetadata - customClientMetadata - protectedAppMetadata - customData - isThirdParty - createdAt - organizationRoles properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 secret: $ref: '#/components/schemas/ApplicationLegacySecret' description: type: string nullable: true type: type: string enum: - Native - SPA - Traditional - MachineToMachine - Protected - SAML oidcClientMetadata: type: object required: - redirectUris - postLogoutRedirectUris properties: redirectUris: type: array items: type: object description: Validator function postLogoutRedirectUris: type: array items: type: object description: Validator function backchannelLogoutUri: type: string format: url backchannelLogoutSessionRequired: type: boolean logoUri: type: string customClientMetadata: type: object properties: corsAllowedOrigins: type: array items: type: string minLength: 1 idTokenTtl: type: number refreshTokenTtl: type: number refreshTokenTtlInDays: type: number tenantId: type: string alwaysIssueRefreshToken: type: boolean rotateRefreshToken: type: boolean allowTokenExchange: type: boolean isDeviceFlow: type: boolean maxAllowedGrants: type: number protectedAppMetadata: type: object required: - host - origin - sessionDuration - pageRules properties: host: type: string origin: type: string sessionDuration: type: number pageRules: type: array items: type: object required: - path properties: path: type: string customDomains: type: array items: type: object required: - domain - status - errorMessage - dnsRecords - cloudflareData properties: domain: type: string status: type: string enum: - PendingVerification - PendingSsl - Active - Error errorMessage: type: string nullable: true dnsRecords: type: array items: type: object required: - name - type - value properties: name: type: string type: type: string value: type: string cloudflareData: type: object required: - id - status - ssl properties: id: type: string status: type: string ssl: type: object required: - status properties: status: type: string validation_errors: type: array items: type: object required: - message properties: message: type: string verification_errors: type: array items: type: string nullable: true nullable: true customData: type: object description: arbitrary isThirdParty: type: boolean createdAt: type: number 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 applications description: Get applications associated with the organization. /api/organizations/{id}/applications/{applicationId}: delete: operationId: DeleteOrganizationApplication tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - $ref: '#/components/parameters/applicationId' responses: '204': description: The application was removed from the organization successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: Unprocessable Content summary: Remove organization application description: Remove an application from the organization. /api/organizations/{id}/applications/roles: post: operationId: AssignOrganizationRolesToApplications tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' requestBody: required: true content: application/json: schema: type: object required: - applicationIds - organizationRoleIds properties: applicationIds: type: array items: type: string minLength: 1 description: An array of application IDs to assign roles to. organizationRoleIds: type: array items: type: string minLength: 1 description: An array of organization role IDs to assign to the applications. responses: '201': description: Roles were assigned to the applications 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, application ID, or organization role ID does not exist; the application is not a member of the organization; or the role type is not assignable to the application. summary: Assign roles to applications in an organization description: Assign roles to applications in the specified organization. /api/organizations/{id}/applications/{applicationId}/roles: get: operationId: ListOrganizationApplicationRoles tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - $ref: '#/components/parameters/applicationId' - 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. 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: Unprocessable Content summary: Get organization application roles description: Get roles associated with the application in the organization. post: operationId: AssignOrganizationRolesToApplication tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - $ref: '#/components/parameters/applicationId' requestBody: required: true content: application/json: schema: type: object required: - organizationRoleIds properties: organizationRoleIds: type: array items: type: string minLength: 1 description: The role ID to add. responses: '201': description: The role was added successfully. content: application/json: {} '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The role could not be added. Some of the roles may not exist. summary: Add organization application role description: Add a role to the application in the organization. put: operationId: ReplaceOrganizationApplicationRoles tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - $ref: '#/components/parameters/applicationId' requestBody: required: true content: application/json: schema: type: object required: - organizationRoleIds properties: organizationRoleIds: type: array items: type: string minLength: 1 description: An array of role IDs to replace existing roles. responses: '204': description: The roles were replaced successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The roles could not be replaced. Some of the roles may not exist. summary: Replace organization application roles description: Replace all roles associated with the application in the organization with the given data. /api/organizations/{id}/applications/{applicationId}/roles/{organizationRoleId}: delete: operationId: DeleteOrganizationApplicationRole tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - $ref: '#/components/parameters/applicationId' - $ref: '#/components/parameters/organizationRoleId' responses: '204': description: The role was removed from the application in the organization successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Cannot find the record to delete. '422': description: The application is not associated with the organization. summary: Remove organization application role description: Remove a role from the application in the organization. /api/organizations/{id}/jit/email-domains: get: operationId: ListOrganizationJitEmailDomains tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - 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 email domains. content: application/json: schema: type: array items: type: object required: - tenantId - organizationId - emailDomain properties: tenantId: type: string maxLength: 21 organizationId: type: string minLength: 1 maxLength: 21 emailDomain: type: string minLength: 1 maxLength: 128 '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden summary: Get organization JIT email domains description: Get email domains for just-in-time provisioning of users in the organization. post: operationId: CreateOrganizationJitEmailDomain tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' requestBody: required: true content: application/json: schema: type: object required: - emailDomain properties: emailDomain: type: string minLength: 1 description: The email domain to add. responses: '201': description: The email domain was added successfully. content: application/json: schema: type: object required: - tenantId - organizationId - emailDomain properties: tenantId: type: string maxLength: 21 organizationId: type: string minLength: 1 maxLength: 21 emailDomain: type: string minLength: 1 maxLength: 128 '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The email domain is already in use. summary: Add organization JIT email domain description: Add a new email domain for just-in-time provisioning of users in the organization. put: operationId: ReplaceOrganizationJitEmailDomains tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' requestBody: required: true content: application/json: schema: type: object required: - emailDomains properties: emailDomains: type: array items: type: string description: An array of email domains to replace existing email domains. responses: '204': description: The email domains were replaced successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden summary: Replace organization JIT email domains description: Replace all just-in-time provisioning email domains for the organization with the given data. /api/organizations/{id}/jit/email-domains/{emailDomain}: delete: operationId: DeleteOrganizationJitEmailDomain tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - name: emailDomain in: path required: true schema: type: string minLength: 1 description: The email domain to remove. responses: '204': description: The email domain was removed successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The email domain was not found. summary: Remove organization JIT email domain description: Remove an email domain for just-in-time provisioning of users in the organization. /api/organizations/{id}/jit/roles: get: operationId: ListOrganizationJitRoles tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - 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 organization roles. 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 '404': description: Not Found summary: Get organization JIT default roles description: Get organization roles that will be assigned to users during just-in-time provisioning. post: operationId: CreateOrganizationJitRole tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' requestBody: required: true content: application/json: schema: type: object required: - organizationRoleIds properties: organizationRoleIds: type: array items: type: string minLength: 1 description: The organization role IDs to add. responses: '201': description: The organization roles were added successfully. content: application/json: {} '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The organization roles could not be added. Some of the organization roles may not exist. summary: Add organization JIT default roles description: Add new organization roles that will be assigned to users during just-in-time provisioning. put: operationId: ReplaceOrganizationJitRoles tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' requestBody: required: true content: application/json: schema: type: object required: - organizationRoleIds properties: organizationRoleIds: type: array items: type: string minLength: 1 description: An array of organization role IDs to replace existing organization roles. responses: '204': description: The organization roles were replaced successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The organization roles could not be replaced. Some of the organization roles may not exist. summary: Replace organization JIT default roles description: Replace all organization roles that will be assigned to users during just-in-time provisioning with the given data. /api/organizations/{id}/jit/roles/{organizationRoleId}: delete: operationId: DeleteOrganizationJitRole tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - $ref: '#/components/parameters/organizationRoleId' responses: '204': description: The organization role was removed successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The organization role could not be removed. The organization role may not exist. summary: Remove organization JIT default role description: Remove an organization role that will be assigned to users during just-in-time provisioning. /api/organizations/{id}/jit/sso-connectors: get: operationId: ListOrganizationJitSsoConnectors tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - 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 SSO connectors. content: application/json: schema: type: array items: type: object required: - tenantId - id - providerName - connectorName - config - domains - branding - syncProfile - enableTokenStorage - createdAt properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 128 providerName: type: string minLength: 1 maxLength: 128 connectorName: type: string minLength: 1 maxLength: 128 config: type: object description: arbitrary domains: type: array items: type: string branding: type: object properties: displayName: type: string logo: type: string darkLogo: type: string syncProfile: type: boolean enableTokenStorage: type: boolean createdAt: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Get organization JIT SSO connectors description: Get enterprise SSO connectors for just-in-time provisioning of users in the organization. post: operationId: CreateOrganizationJitSsoConnector tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' requestBody: required: true content: application/json: schema: type: object required: - ssoConnectorIds properties: ssoConnectorIds: type: array items: type: string minLength: 1 description: The SSO connector IDs to add. responses: '201': description: The SSO connectors were added successfully. content: application/json: {} '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The SSO connectors could not be added. Some of the SSO connectors may not exist. summary: Add organization JIT SSO connectors description: Add new enterprise SSO connectors for just-in-time provisioning of users in the organization. put: operationId: ReplaceOrganizationJitSsoConnectors tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' requestBody: required: true content: application/json: schema: type: object required: - ssoConnectorIds properties: ssoConnectorIds: type: array items: type: string minLength: 1 description: An array of SSO connector IDs to replace existing SSO connectors. responses: '204': description: The SSO connectors were replaced successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The SSO connectors could not be replaced. Some of the SSO connectors may not exist. summary: Replace organization JIT SSO connectors description: Replace all enterprise SSO connectors for just-in-time provisioning of users in the organization with the given data. /api/organizations/{id}/jit/sso-connectors/{ssoConnectorId}: delete: operationId: DeleteOrganizationJitSsoConnector tags: - Organizations parameters: - $ref: '#/components/parameters/organizationId-root' - $ref: '#/components/parameters/ssoConnectorId' responses: '204': description: The SSO connector was removed successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The SSO connector could not be removed. The SSO connector may not exist. summary: Remove organization JIT SSO connector description: Remove an enterprise SSO connector for just-in-time provisioning of users in the organization. components: schemas: ApplicationLegacySecret: type: string deprecated: true description: The internal client secret. Note it is only used for internal validation, and the actual secrets should be retrieved from `/api/applications/{id}/secrets` endpoints. parameters: applicationId: in: path description: The unique identifier of the application. required: true schema: type: string name: applicationId organizationId-root: in: path description: The unique identifier of the organization. required: true schema: type: string name: id ssoConnectorId: in: path description: The unique identifier of the sso connector. required: true schema: type: string name: ssoConnectorId organizationRoleId: in: path description: The unique identifier of the organization role. required: true schema: type: string name: organizationRoleId userId: in: path description: The unique identifier of the user. required: true schema: type: string name: userId securitySchemes: OAuth2: type: oauth2 description: "Logto Management API is a comprehensive set of REST APIs that gives you the full control over Logto to suit your product needs and tech stack. To see the full guide on Management API interactions, visit [Interact with Management API](https://docs.logto.io/docs/recipes/interact-with-management-api/).\n\n### Get started\n\nThe API follows the same authentication principles as other API resources in Logto, with some slight differences. To use Logto Management API:\n\n1. A machine-to-machine (M2M) application needs to be created.\n2. A machine-to-machine (M2M) role with Management API permission `all` needs to be assigned to the application.\n\nOnce you have them set up, you can use the `client_credentials` grant type to fetch an access token and use it to authenticate your requests to the Logto Management API.\n\n### Fetch an access token\n\nTo fetch an access token, you need to make a `POST` request to the `/oidc/token` endpoint of your Logto tenant.\n\nFor Logto Cloud users, the base URL is your Logto endpoint, i.e. `https://[tenant-id].logto.app`. The tenant ID can be found in the following places:\n\n- The first path segment of the URL when you are signed in to Logto Cloud. For example, if the URL is `https://cloud.logto.io/foo/get-started`, the tenant ID is `foo`.\n- In the \"Settings\" tab of Logto Cloud.\n\nThe request should follow the OAuth 2.0 [client credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) grant type. Here is a non-normative example of how to fetch an access token:\n\n```bash\ncurl --location \\\n --request POST 'https://[tenant-id].logto.app/oidc/token' \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'grant_type=client_credentials' \\\n --data-urlencode 'client_id=[app-id]' \\\n --data-urlencode 'client_secret=[app-secret]' \\\n --data-urlencode 'resource=https://[tenant-id].logto.app/api' \\\n --data-urlencode 'scope=all'\n```\n\nReplace `[tenant-id]`, `[app-id]`, and `[app-secret]` with your Logto tenant ID, application ID, and application secret, respectively.\n\nThe response will be like:\n\n```json\n{\n \"access_token\": \"eyJhbG...2g\", // Use this value for accessing the Logto Management API\n \"expires_in\": 3600, // Token expiration in seconds\n \"token_type\": \"Bearer\", // Token type for your request when using the access token\n \"scope\": \"all\" // Scope `all` for Logto Management API\n}\n```\n\n### Use the access token\n\nOnce you have the access token, you can use it to authenticate your requests to the Logto Management API. The access token should be included in the `Authorization` header of your requests with the `Bearer` authentication scheme.\n\nHere is an example of how to list the first page of users in your Logto tenant:\n\n```bash\ncurl --location \\\n --request GET 'https://[tenant-id].logto.app/api/users' \\\n --header 'Authorization: Bearer eyJhbG...2g'\n```\n\nReplace `[tenant-id]` with your Logto tenant ID and `eyJhbG...2g` with the access token you fetched earlier." flows: clientCredentials: tokenUrl: /oidc/token scopes: all: All scopes