Logto Roles API
Role management for API resource RBAC (role-based access control). See [🔐 Role-based access control (RBAC)](https://docs.logto.io/docs/recipes/rbac/) to get started with role-based access control.
OpenAPI Specification
openapi: 3.0.1
info:
title: Logto API references Account center 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: Roles
description: Role management for API resource RBAC (role-based access control). See [🔐 Role-based access control (RBAC)](https://docs.logto.io/docs/recipes/rbac/) to get started with role-based access control.
paths:
/api/roles:
get:
operationId: ListRoles
tags:
- Roles
parameters:
- name: excludeUserId
in: query
required: false
schema:
type: string
description: Exclude roles assigned to a user.
- name: excludeApplicationId
in: query
required: false
schema:
type: string
description: Exclude roles assigned to an application.
- name: type
in: query
required: false
schema:
type: string
enum:
- User
- MachineToMachine
description: Filter by role type.
- 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
- name: search_params
in: query
description: Search query parameters.
required: false
schema:
type: object
additionalProperties:
type: string
explode: true
responses:
'200':
description: An array of roles matching the filters.
content:
application/json:
schema:
type: array
items:
type: object
required:
- tenantId
- id
- name
- description
- type
- isDefault
- usersCount
- featuredUsers
- applicationsCount
- featuredApplications
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description:
type: string
minLength: 1
maxLength: 128
type:
type: string
enum:
- User
- MachineToMachine
isDefault:
type: boolean
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
applicationsCount:
type: number
featuredApplications:
type: array
items:
type: object
required:
- id
- name
- type
properties:
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 256
type:
type: string
enum:
- Native
- SPA
- Traditional
- MachineToMachine
- Protected
- SAML
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Get roles
description: Get roles with filters and pagination.
post:
operationId: CreateRole
tags:
- Roles
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- description
properties:
tenantId:
type: string
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description: The name of the role. It should be unique within the tenant.
description:
type: string
minLength: 1
maxLength: 128
type:
type: string
enum:
- User
- MachineToMachine
description: The type of the role. It cannot be changed after creation.
isDefault:
type: boolean
scopeIds:
type: array
items:
type: string
minLength: 1
description: The initial API resource scopes assigned to the role.
responses:
'200':
description: The created role.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- name
- description
- type
- isDefault
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description:
type: string
minLength: 1
maxLength: 128
type:
type: string
enum:
- User
- MachineToMachine
isDefault:
type: boolean
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Content
summary: Create a role
description: Create a new role with the given data.
/api/roles/{id}:
get:
operationId: GetRole
tags:
- Roles
parameters:
- $ref: '#/components/parameters/roleId-root'
responses:
'200':
description: Details of the role.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- name
- description
- type
- isDefault
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description:
type: string
minLength: 1
maxLength: 128
type:
type: string
enum:
- User
- MachineToMachine
isDefault:
type: boolean
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Get role
description: Get role details by ID.
patch:
operationId: UpdateRole
tags:
- Roles
parameters:
- $ref: '#/components/parameters/roleId-root'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 128
description: The name of the role. It should be unique within the tenant.
description:
type: string
minLength: 1
maxLength: 128
isDefault:
type: boolean
responses:
'200':
description: The updated role.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- name
- description
- type
- isDefault
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description:
type: string
minLength: 1
maxLength: 128
type:
type: string
enum:
- User
- MachineToMachine
isDefault:
type: boolean
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Content
summary: Update role
description: Update role details. This method performs a partial update.
delete:
operationId: DeleteRole
tags:
- Roles
parameters:
- $ref: '#/components/parameters/roleId-root'
responses:
'204':
description: The role was deleted.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Delete role
description: Delete a role with the given ID.
/api/roles/{id}/users:
get:
operationId: ListRoleUsers
tags:
- Roles
parameters:
- $ref: '#/components/parameters/roleId-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
- name: search_params
in: query
description: Search query parameters.
required: false
schema:
type: object
additionalProperties:
type: string
explode: true
responses:
'200':
description: An array of users who have the role assigned.
content:
application/json:
schema:
type: array
items:
type: object
required:
- id
- username
- primaryEmail
- primaryPhone
- name
- avatar
- customData
- identities
- lastSignInAt
- createdAt
- updatedAt
- profile
- applicationId
- isSuspended
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
hasPassword:
type: boolean
ssoIdentities:
type: array
items:
type: object
required:
- tenantId
- id
- userId
- issuer
- identityId
- detail
- createdAt
- updatedAt
- ssoConnectorId
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
userId:
type: string
minLength: 1
maxLength: 12
issuer:
type: string
minLength: 1
maxLength: 256
identityId:
type: string
minLength: 1
maxLength: 128
detail:
type: object
description: arbitrary
createdAt:
type: number
updatedAt:
type: number
ssoConnectorId:
type: string
minLength: 1
maxLength: 128
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Get role users
description: Get users who have the role assigned with pagination.
post:
operationId: CreateRoleUser
tags:
- Roles
parameters:
- $ref: '#/components/parameters/roleId-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 assigned.
responses:
'201':
description: The role was assigned to the users successfully.
content:
application/json: {}
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Content
summary: Assign role to users
description: Assign a role to a list of users. The role must have the type `User`.
/api/roles/{id}/users/{userId}:
delete:
operationId: DeleteRoleUser
tags:
- Roles
parameters:
- $ref: '#/components/parameters/roleId-root'
- $ref: '#/components/parameters/userId'
responses:
'204':
description: The role was removed from the user.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Remove role from user
description: Remove a role from a user with the given ID.
/api/roles/{id}/applications:
get:
operationId: ListRoleApplications
tags:
- Roles
parameters:
- $ref: '#/components/parameters/roleId-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
- name: search_params
in: query
description: Search query parameters.
required: false
schema:
type: object
additionalProperties:
type: string
explode: true
responses:
'200':
description: An array of applications that have the role assigned.
content:
application/json:
schema:
type: array
items:
type: object
required:
- tenantId
- id
- name
- secret
- description
- type
- oidcClientMetadata
- customClientMetadata
- protectedAppMetadata
- customData
- isThirdParty
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 256
secret:
type: string
minLength: 1
maxLength: 64
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
'204':
description: No Content
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Get role applications
description: Get applications that have the role assigned with pagination.
post:
operationId: CreateRoleApplication
tags:
- Roles
parameters:
- $ref: '#/components/parameters/roleId-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 be assigned.
responses:
'201':
description: The role was assigned to the applications successfully.
content:
application/json: {}
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Content
summary: Assign role to applications
description: Assign a role to a list of applications. The role must have the type `Application`.
/api/roles/{id}/applications/{applicationId}:
delete:
operationId: DeleteRoleApplication
tags:
- Roles
parameters:
- $ref: '#/components/parameters/roleId-root'
- $ref: '#/components/parameters/applicationId'
responses:
'204':
description: The role was removed from the application.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Remove role from application
description: Remove the role from an application with the given ID.
/api/roles/{id}/scopes:
get:
operationId: ListRoleScopes
tags:
- Roles
parameters:
- $ref: '#/components/parameters/roleId-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
- name: search_params
in: query
description: Search query parameters.
required: false
schema:
type: object
additionalProperties:
type: string
explode: true
responses:
'200':
description: An array of API resource scopes linked with the role.
content:
application/json:
schema:
type: array
items:
type: object
required:
- tenantId
- id
- resourceId
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/logto/refs/heads/main/openapi/logto-roles-api-openapi.yml