Logto Applications API

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:
                    

# --- truncated at 32 KB (103 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/logto/refs/heads/main/openapi/logto-applications-api-openapi.yml