openapi: 3.0.1 info: title: Logto API references Account center Applications 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: Applications description: 'Application represents your registered software program or service that has been authorized to access user information and perform actions on behalf of users within the system. Currently, Logto supports four types of applications: - Traditional web - Single-page app - Native app - Machine-to-machine app. Depending on the application type, it may have different authentication flows and access to the system. See [🔗 Integrate Logto in your application](https://docs.logto.io/docs/recipes/integrate-logto/) to learn more about how to integrate Logto into your application. Role-based access control (RBAC) is supported for machine-to-machine applications. See [🔐 Role-based access control (RBAC)](https://docs.logto.io/docs/recipes/rbac/) to get started with role-based access control.' paths: /api/applications: get: operationId: ListApplications tags: - Applications parameters: - name: types in: query required: false schema: oneOf: - type: array items: type: string enum: - Native - SPA - Traditional - MachineToMachine - Protected - SAML - type: string enum: - Native - SPA - Traditional - MachineToMachine - Protected - SAML description: An array of application types to filter applications. - name: excludeRoleId in: query required: false schema: type: string - name: excludeOrganizationId in: query required: false schema: type: string - name: isThirdParty in: query required: false schema: oneOf: - type: string format: '"true"' - type: string format: '"false"' - 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: 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 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 '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden summary: Get applications description: Get applications that match the given query with pagination. post: operationId: CreateApplication tags: - Applications parameters: [] requestBody: required: true content: application/json: schema: type: object required: - name - type properties: name: type: string minLength: 1 maxLength: 256 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 customData: type: object description: arbitrary isThirdParty: type: boolean protectedAppMetadata: type: object required: - subDomain - origin properties: subDomain: type: string description: The subdomain prefix, e.g., my-site. origin: type: string description: The origin of target website, e.g., https://example.com. description: The data for protected app, this feature is not available for open source version. responses: '200': description: The application was created successfully. content: application/json: schema: 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: $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 '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: Validation error. Please check the request body. '500': description: Internal Server Error summary: Create an application description: Create a new application with the given data. /api/applications/{id}: get: operationId: GetApplication tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' responses: '200': description: Details of the application. content: application/json: schema: type: object required: - tenantId - id - name - secret - description - type - oidcClientMetadata - customClientMetadata - protectedAppMetadata - customData - isThirdParty - createdAt - isAdmin 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 isAdmin: type: boolean '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The application with the specified ID was not found. summary: Get application description: Get application details by ID. patch: operationId: UpdateApplication tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 256 description: type: string nullable: true 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 customData: type: object description: arbitrary protectedAppMetadata: type: object properties: origin: type: string sessionDuration: type: number pageRules: type: array items: type: object required: - path properties: path: type: string nullable: true isAdmin: type: boolean description: Whether the application has admin access. User can enable the admin access for Machine-to-Machine apps. responses: '200': description: The application was updated successfully. content: application/json: schema: 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: $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 '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The application with the specified ID was not found. '422': description: Validation error. Please check the request body. '500': description: Internal server error. summary: Update application description: Update application details by ID with the given data. delete: operationId: DeleteApplication tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' responses: '204': description: The application was deleted successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The application with the specified ID was not found. '422': description: Unprocessable Content summary: Delete application description: Delete application by ID. /api/applications/{applicationId}/custom-data: patch: operationId: UpdateApplicationCustomData tags: - Applications parameters: - $ref: '#/components/parameters/applicationId' requestBody: required: true content: application/json: schema: type: object description: An arbitrary JSON object. responses: '200': description: The updated custom data in JSON. content: application/json: schema: type: object description: arbitrary '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden summary: Update application custom data description: Update the custom data of an application. /api/applications/{applicationId}/roles: get: operationId: ListApplicationRoles tags: - Applications parameters: - $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 - 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 roles assigned to the application. content: application/json: schema: type: array items: 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: Get application API resource roles description: Get API resource roles assigned to the specified application with pagination. post: operationId: AssignApplicationRoles tags: - Applications parameters: - $ref: '#/components/parameters/applicationId' requestBody: required: true content: application/json: schema: type: object required: - roleIds properties: roleIds: type: array items: type: string minLength: 1 description: An array of API resource role IDs to assign. responses: '201': description: The API resource roles have been assigned to the application successfully. content: application/json: {} '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Content summary: Assign API resource roles to application description: Assign API resource roles to the specified application. The API resource roles will be added to the existing API resource roles. put: operationId: ReplaceApplicationRoles tags: - Applications parameters: - $ref: '#/components/parameters/applicationId' requestBody: required: true content: application/json: schema: type: object required: - roleIds properties: roleIds: type: array items: type: string minLength: 1 description: An array of API resource role IDs to update for the application. responses: '200': description: The API resource roles have been updated for the application successfully. content: application/json: {} '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Content summary: Update API resource roles for application description: Update API resource roles assigned to the specified application. This will replace the existing API resource roles. /api/applications/{applicationId}/roles/{roleId}: delete: operationId: DeleteApplicationRole tags: - Applications parameters: - $ref: '#/components/parameters/applicationId' - $ref: '#/components/parameters/roleId' responses: '204': description: The API resource role has been removed from the application successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Content summary: Remove a API resource role from application description: Remove a API resource role from the specified application. /api/applications/{id}/protected-app-metadata/custom-domains: get: operationId: ListApplicationProtectedAppMetadataCustomDomains tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' responses: '200': description: An array of the application custom domains. content: application/json: schema: 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 '400': description: Faild to sync the domain info from remote provider. '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '501': description: Not Implemented summary: Get application custom domains. description: Get custom domains of the specified application, the application type should be protected app. post: operationId: CreateApplicationProtectedAppMetadataCustomDomain tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' requestBody: required: true content: application/json: schema: type: object required: - domain properties: domain: type: string description: The domain to be added to the application. responses: '201': description: The domain has been added to the application. content: application/json: {} '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '409': description: The domain already exists. '422': description: Exeeded the maximum number of domains allowed or the domain is invalid. '501': description: Not Implemented summary: Add a custom domain to the application. description: Add a custom domain to the application. You'll need to setup DNS record later. /api/applications/{id}/protected-app-metadata/custom-domains/{domain}: delete: operationId: DeleteApplicationProtectedAppMetadataCustomDomain tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' - name: domain in: path required: true schema: type: string responses: '204': description: The domain has been removed. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Can not find the domain. '501': description: Not Implemented summary: Remove custom domain. description: Remove custom domain from the specified application. /api/applications/{id}/organizations: get: operationId: ListApplicationOrganizations tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-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: An array of organizations that the application is associated with. content: application/json: schema: type: array items: type: object required: - tenantId - id - name - description - customData - isMfaRequired - color - branding - customCss - createdAt - organizationRoles 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 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 application organizations description: Get the list of organizations that an application is associated with. /api/applications/{id}/legacy-secret: delete: operationId: DeleteApplicationLegacySecret tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' responses: '200': description: OK content: application/json: schema: 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: The legacy secret was deleted successfully. '400': description: The application does not have a legacy secret. '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Delete application legacy secret description: 'Delete the legacy secret for the application and replace it with a new internal secret. Note: This operation does not "really" delete the legacy secret because it is still needed for internal validation. We may remove the display of the legacy secret (the `secret` field in the application response) in the future.' /api/applications/{id}/secrets: get: operationId: ListApplicationSecrets tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' responses: '200': description: A list of secrets. content: application/json: schema: type: array items: type: object required: - tenantId - applicationId - name - value - createdAt - expiresAt properties: tenantId: type: string maxLength: 21 applicationId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 value: type: string minLength: 1 maxLength: 64 createdAt: type: number expiresAt: type: number nullable: true '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Get application secrets description: Get all the secrets for the application. post: operationId: CreateApplicationSecret tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string minLength: 1 maxLength: 256 description: The secret name. Must be unique within the application. expiresAt: type: number nullable: true description: The epoch time in milliseconds when the secret will expire. If not provided, the secret will never expire. responses: '201': description: The secret was added successfully. content: application/json: schema: type: object required: - tenantId - applicationId - name - value - createdAt - expiresAt properties: tenantId: type: string maxLength: 21 applicationId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 value: type: string minLength: 1 maxLength: 64 createdAt: type: number expiresAt: type: number nullable: true '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The secret name is already in use. summary: Add application secret description: Add a new secret for the application. /api/applications/{id}/secrets/{name}: delete: operationId: DeleteApplicationSecret tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' - name: name in: path required: true schema: type: string description: The name of the secret. responses: '204': description: The secret was deleted successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Delete application secret description: Delete a secret for the application by name. patch: operationId: UpdateApplicationSecret tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' - name: name in: path required: true schema: type: string description: The name of the secret. requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string minLength: 1 maxLength: 256 description: The secret name to update. Must be unique within the application. responses: '200': description: OK content: application/json: schema: type: object required: - tenantId - applicationId - name - value - createdAt - expiresAt properties: tenantId: type: string maxLength: 21 applicationId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 value: type: string minLength: 1 maxLength: 64 createdAt: type: number expiresAt: type: number nullable: true '204': description: The secret was updated successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Update application secret description: Update a secret for the application by name. /api/applications/{applicationId}/user-consent-scopes: post: operationId: CreateApplicationUserConsentScope tags: - Applications parameters: - $ref: '#/components/parameters/applicationId' requestBody: required: true content: application/json: schema: type: object properties: organizationScopes: type: array items: type: string description: A list of organization scope id to assign to the application. Throws error if any given organization scope is not found. resourceScopes: type: array items: type: string description: A list of resource scope id to assign to the application. Throws error if any given resource scope is not found. organizationResourceScopes: type: array items: type: string description: A list of organization resource scope id to assign to the application. Throws error if any given resource scope is not found. userScopes: type: array items: type: string enum: - profile - email - phone - address - custom_data - identities - roles - urn:logto:scope:organizations - urn:logto:scope:organization_roles - urn:logto:scope:sessions description: A list of user scope enum value to assign to the application. responses: '201': description: All the user consent scopes are assigned to the application successfully content: application/json: {} '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The application is not found '422': description: Any of the given organization scope, resource scope or user scope is not found summary: Assign user consent scopes to application. description: Assign the user consent scopes to an application by application id get: operationId: ListApplicationUserConsentScopes tags: - Applications parameters: - $ref: '#/components/parameters/applicationId' responses: '200': description: All the user consent scopes of the application are listed successfully content: application/json: schema: type: object required: - organizationScopes - resourceScopes - organizationResourceScopes - userScopes properties: organizationScopes: type: array items: type: object required: - id - name - description properties: id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 128 description: type: string maxLength: 256 nullable: true description: A list of organization scope details assigned to the application. resourceScopes: type: array items: type: object required: - resource - scopes properties: resource: type: object required: - id - name - indicator properties: id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 indicator: type: string minLength: 1 scopes: type: array items: type: object required: - id - name - description properties: id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 description: type: string nullable: true description: A list of resource scope details grouped by resource id assigned to the application. organizationResourceScopes: type: array items: type: object required: - resource - scopes properties: resource: type: object required: - id - name - indicator properties: id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 indicator: type: string minLength: 1 scopes: type: array items: type: object required: - id - name - description properties: id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 description: type: string nullable: true description: A list of organization resource scope details grouped by resource id assigned to the application. userScopes: type: array items: type: string enum: - profile - email - phone - address - custom_data - identities - roles - urn:logto:scope:organizations - urn:logto:scope:organization_roles - urn:logto:scope:sessions description: A list of user scope enum value assigned to the application. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The application is not found summary: List all the user consent scopes of an application. description: List all the user consent scopes of an application by application id /api/applications/{applicationId}/user-consent-scopes/{scopeType}/{scopeId}: delete: operationId: DeleteApplicationUserConsentScope tags: - Applications parameters: - $ref: '#/components/parameters/applicationId' - name: scopeType in: path required: true schema: type: string enum: - organization-scopes - resource-scopes - organization-resource-scopes - user-scopes - $ref: '#/components/parameters/scopeId' responses: '204': description: The user consent scope is removed from the application successfully '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The application or scope is not found summary: Remove user consent scope from application. description: Remove the user consent scope from an application by application id, scope type and scope id /api/applications/{applicationId}/sign-in-experience: put: operationId: ReplaceApplicationSignInExperience tags: - Applications parameters: - $ref: '#/components/parameters/applicationId' requestBody: required: true content: application/json: schema: type: object required: - termsOfUseUrl - privacyPolicyUrl properties: 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 displayName: type: string maxLength: 256 nullable: true termsOfUseUrl: oneOf: - type: string format: url maxLength: 2048 nullable: true - type: string format: empty privacyPolicyUrl: oneOf: - type: string format: url maxLength: 2048 nullable: true - type: string format: empty responses: '200': description: The application's sign-in experience was successfully updated. content: application/json: schema: type: object required: - tenantId - applicationId - color - branding - customCss - termsOfUseUrl - privacyPolicyUrl - displayName properties: tenantId: type: string maxLength: 21 applicationId: type: string minLength: 1 maxLength: 21 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 termsOfUseUrl: type: string maxLength: 2048 nullable: true privacyPolicyUrl: type: string maxLength: 2048 nullable: true displayName: type: string maxLength: 256 nullable: true '201': description: A new application level sign-in experience settings was successfully created. content: application/json: schema: type: object required: - tenantId - applicationId - color - branding - customCss - termsOfUseUrl - privacyPolicyUrl - displayName properties: tenantId: type: string maxLength: 21 applicationId: type: string minLength: 1 maxLength: 21 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 termsOfUseUrl: type: string maxLength: 2048 nullable: true privacyPolicyUrl: type: string maxLength: 2048 nullable: true displayName: type: string maxLength: 256 nullable: true '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The application does not exist. '422': description: Unprocessable Content summary: Update application level sign-in experience description: "Update application level sign-in experience for the specified application. Create a new sign-in experience if it does not exist. \n - Only branding properties and terms links customization is supported for now. \n\n - Only third-party applications can be customized for now. \n\n - Application level sign-in experience customization is optional, if provided, it will override the default branding and terms links." get: operationId: GetApplicationSignInExperience tags: - Applications parameters: - $ref: '#/components/parameters/applicationId' responses: '200': description: Returns the application's application level sign-in experience. content: application/json: schema: type: object required: - tenantId - applicationId - color - branding - customCss - termsOfUseUrl - privacyPolicyUrl - displayName properties: tenantId: type: string maxLength: 21 applicationId: type: string minLength: 1 maxLength: 21 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 termsOfUseUrl: type: string maxLength: 2048 nullable: true privacyPolicyUrl: type: string maxLength: 2048 nullable: true displayName: type: string maxLength: 256 nullable: true '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The application does not exist or the application level sign-in experience does not exist. summary: Get the application level sign-in experience description: "Get application level sign-in experience for a given application. \n - Only branding properties and terms links customization is supported for now. \n\n - Only third-party applications can have the sign-in experience customization for now." /api/applications/{id}/users/{userId}/consent-organizations: get: operationId: ListApplicationUserConsentOrganizations tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-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: List of organization entities granted by the user for the application. content: application/json: schema: type: object required: - organizations properties: organizations: 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 description: A list of organization entities granted by the user for the application. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Content summary: List all the user consented organizations of a application. description: List all the user consented organizations for a application by application id and user id. put: operationId: ReplaceApplicationUserConsentOrganizations tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: type: object required: - organizationIds properties: organizationIds: type: array items: type: string minLength: 1 description: A list of organization ids to be granted.
All the existing organizations' access will be revoked if not in the list.
If the list is empty, all the organizations' access will be revoked. responses: '204': description: 'All the request organizations''s access are granted to the user for the application. ' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The application or user is not found. '422': description: The user is not a member of one of the organizations, or the application is not a third-party application. summary: Grant a list of organization access of a user for a application. description: Grant a list of organization access of a user for a application by application id and user id.
The user must be a member of all the organizations.
Only third-party application needs to be granted access to organizations, all the other applications can request for all the organizations' access by default. post: operationId: CreateApplicationUserConsentOrganization tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: type: object required: - organizationIds properties: organizationIds: type: array items: type: string minLength: 1 description: A list of organization ids to be granted. responses: '201': description: All the request organizations's access are granted to the user for the application. content: application/json: {} '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The application or user is not found. '422': description: The user is not a member of one of the organizations, or the application is not a third-party application. summary: Grant a list of organization access of a user for a application. description: Grant a list of organization access of a user for a application by application id and user id.
The user must be a member of all the organizations.
Only third-party application needs to be granted access to organizations, all the other applications can request for all the organizations' access by default. /api/applications/{id}/users/{userId}/consent-organizations/{organizationId}: delete: operationId: DeleteApplicationUserConsentOrganization tags: - Applications parameters: - $ref: '#/components/parameters/applicationId-root' - $ref: '#/components/parameters/userId' - $ref: '#/components/parameters/organizationId' responses: '204': description: The user's access to the organization is revoked for the application. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The application, user or organization is not found. '422': description: Unprocessable Content summary: Revoke a user's access to an organization for a application. description: Revoke a user's access to an organization for a application by application id, user id and organization id. components: parameters: applicationId: in: path description: The unique identifier of the application. required: true schema: type: string name: applicationId organizationId: in: path description: The unique identifier of the organization. required: true schema: type: string name: organizationId roleId: in: path description: The unique identifier of the role. required: true schema: type: string name: roleId userId: in: path description: The unique identifier of the user. required: true schema: type: string name: userId applicationId-root: in: path description: The unique identifier of the application. required: true schema: type: string name: id scopeId: in: path description: The unique identifier of the scope. required: true schema: type: string name: scopeId 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. 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