openapi: 3.0.1 info: title: Logto API references Account center Organization roles 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: Organization roles description: 'Organization roles are used to define a set of organization scopes that can be assigned to users. Every organization role is a part of the organization template. Organization roles will only be meaningful within an organization context. For example, a user may have an `admin` role for organization A, but not for organization B. See [🏢 Organizations (Multi-tenancy)](https://docs.logto.io/docs/recipes/organizations/) to get started with organizations and organization template.' paths: /api/organization-roles/{id}: get: operationId: GetOrganizationRole tags: - Organization roles parameters: - $ref: '#/components/parameters/organizationRoleId-root' responses: '200': description: Details of the organization role. content: application/json: schema: 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 role description: Get organization role details by ID. patch: operationId: UpdateOrganizationRole tags: - Organization roles parameters: - $ref: '#/components/parameters/organizationRoleId-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 role. It must be unique within the organization template. description: type: string maxLength: 256 nullable: true description: The updated description of the organization role. type: type: string enum: - User - MachineToMachine responses: '200': description: The organization role was updated successfully. content: application/json: schema: 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 '422': description: The organization role name is already in use. summary: Update organization role description: Update organization role details by ID with the given data. delete: operationId: DeleteOrganizationRole tags: - Organization roles parameters: - $ref: '#/components/parameters/organizationRoleId-root' responses: '204': description: The organization role was deleted successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Delete organization role description: Delete organization role by ID. /api/organization-roles: get: operationId: ListOrganizationRoles tags: - Organization roles parameters: - 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 organization roles. content: application/json: schema: type: array items: type: object required: - tenantId - id - name - description - type - scopes - resourceScopes 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 scopes: type: array items: type: object required: - id - name properties: id: type: string name: type: string resourceScopes: type: array items: type: object required: - id - name - resource properties: id: type: string name: type: string resource: type: object required: - id - name properties: id: type: string name: type: string '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden summary: Get organization roles description: Get organization roles with pagination. post: operationId: CreateOrganizationRole tags: - Organization roles parameters: [] requestBody: required: true content: application/json: schema: type: object required: - name - organizationScopeIds - resourceScopeIds properties: tenantId: type: string maxLength: 21 name: type: string minLength: 1 maxLength: 128 description: The name of the organization role. It must be unique within the organization template. description: type: string maxLength: 256 nullable: true description: The description of the organization role. type: type: string enum: - User - MachineToMachine organizationScopeIds: default: [] type: array items: type: string description: An array of organization scope IDs to be assigned to the organization role. resourceScopeIds: default: [] type: array items: type: string description: An array of resource scope IDs to be assigned to the organization role. responses: '201': description: The organization role was created successfully. content: application/json: schema: 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 organization role name is already in use. summary: Create an organization role description: Create a new organization role with the given data. /api/organization-roles/{id}/scopes: get: operationId: ListOrganizationRoleScopes tags: - Organization roles parameters: - $ref: '#/components/parameters/organizationRoleId-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 scopes. 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 '404': description: Not Found summary: Get organization role scopes description: Get organization scopes that are assigned to the specified organization role with optional pagination. post: operationId: CreateOrganizationRoleScope tags: - Organization roles parameters: - $ref: '#/components/parameters/organizationRoleId-root' requestBody: required: true content: application/json: schema: type: object required: - organizationScopeIds properties: organizationScopeIds: type: array items: type: string minLength: 1 description: An array of organization scope IDs to be assigned. Existed scope IDs assignments will be ignored. responses: '201': description: Organization scopes were assigned successfully. content: application/json: {} '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: At least one of the IDs provided is invalid. For example, the organization scope ID does not exist; summary: Assign organization scopes to organization role description: Assign organization scopes to the specified organization role put: operationId: ReplaceOrganizationRoleScopes tags: - Organization roles parameters: - $ref: '#/components/parameters/organizationRoleId-root' requestBody: required: true content: application/json: schema: type: object required: - organizationScopeIds properties: organizationScopeIds: type: array items: type: string minLength: 1 description: An array of organization scope IDs to replace existing scopes. responses: '204': description: Organization scopes were replaced successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: At least one of the IDs provided is invalid. For example, the organization scope ID does not exist. summary: Replace organization scopes for organization role description: Replace all organization scopes that are assigned to the specified organization role with the given organization scopes. This effectively removes all existing organization scope assignments and replaces them with the new ones. /api/organization-roles/{id}/scopes/{organizationScopeId}: delete: operationId: DeleteOrganizationRoleScope tags: - Organization roles parameters: - $ref: '#/components/parameters/organizationRoleId-root' - $ref: '#/components/parameters/organizationScopeId' responses: '204': description: Organization scope assignment was removed successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: Unprocessable Content summary: Remove organization scope description: Remove a organization scope assignment from the specified organization role. /api/organization-roles/{id}/resource-scopes: get: operationId: ListOrganizationRoleResourceScopes tags: - Organization roles parameters: - $ref: '#/components/parameters/organizationRoleId-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 resource scopes. content: application/json: schema: type: array items: type: object required: - tenantId - id - resourceId - name - description - createdAt properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 resourceId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 description: type: string nullable: true createdAt: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Get organization role resource scopes description: Get resource scopes that are assigned to the specified organization role with optional pagination. post: operationId: CreateOrganizationRoleResourceScope tags: - Organization roles parameters: - $ref: '#/components/parameters/organizationRoleId-root' requestBody: required: true content: application/json: schema: type: object required: - scopeIds properties: scopeIds: type: array items: type: string minLength: 1 description: An array of resource scope IDs to be assigned. Existed scope IDs assignments will be ignored. responses: '201': description: Resource scopes were assigned successfully. content: application/json: {} '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: At least one of the IDs provided is invalid. For example, the resource scope ID does not exist; summary: Assign resource scopes to organization role description: Assign resource scopes to the specified organization role put: operationId: ReplaceOrganizationRoleResourceScopes tags: - Organization roles parameters: - $ref: '#/components/parameters/organizationRoleId-root' requestBody: required: true content: application/json: schema: type: object required: - scopeIds properties: scopeIds: type: array items: type: string minLength: 1 description: An array of resource scope IDs to replace existing scopes. responses: '204': description: Resource scopes were replaced successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: At least one of the IDs provided is invalid. For example, the resource scope ID does not exist. summary: Replace resource scopes for organization role description: Replace all resource scopes that are assigned to the specified organization role with the given resource scopes. This effectively removes all existing organization scope assignments and replaces them with the new ones. /api/organization-roles/{id}/resource-scopes/{scopeId}: delete: operationId: DeleteOrganizationRoleResourceScope tags: - Organization roles parameters: - $ref: '#/components/parameters/organizationRoleId-root' - $ref: '#/components/parameters/scopeId' responses: '204': description: Resource scope assignment was removed successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: Unprocessable Content summary: Remove resource scope description: Remove a resource scope assignment from the specified organization role. components: parameters: organizationRoleId-root: in: path description: The unique identifier of the organization role. required: true schema: type: string name: id organizationScopeId: in: path description: The unique identifier of the organization scope. required: true schema: type: string name: organizationScopeId scopeId: in: path description: The unique identifier of the scope. required: true schema: type: string name: scopeId 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