WSO2 Applications API

openapi: 3.2.0
info:
  title: Wso2 Applications API
  contact:
    name: WSO2
    url: https://wso2.com/api-manager/
    email: architecture@wso2.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: '1.0'
  description: 'Operations tagged Applications across 2 of this provider''s published API definitions: wso2-admin-api.yaml, wso2-devportal-api.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://apis.wso2.com/api/am/admin/v4
- url: https://apis.wso2.com/api/am/devportal/v3
tags:
- name: Applications
paths:
  /applications/{applicationId}:
    get:
      tags:
      - Applications
      summary: Get the details of an Application
      description: This operation can be used to get the details of an application by specifying its id.
      parameters:
      - $ref: '#/components/parameters/applicationId'
      responses:
        200:
          description: 'OK.

            Application details returned.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
        406:
          $ref: '#/components/responses/NotAcceptable'
      security:
      - OAuth2Security:
        - apim:admin
        - apim:app_import_export
        - apim:admin_application_view
      x-code-samples:
      - lang: Curl
        source: 'curl -k -X GET -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" "https://127.0.0.1:9443/api/am/admin/v4/applications/0a043c2b-ee75-4ef3-9e1c-fc2610ccfa8b"'
      operationId: getApplicationsByApplicationId
      x-operation-id-source: derived
    delete:
      tags:
      - Applications
      summary: Delete an Application
      description: This operation can be used to delete an application by specifying its id.
      parameters:
      - $ref: '#/components/parameters/applicationId'
      responses:
        200:
          description: 'OK.

            Resource successfully deleted.

            '
          content: {}
        202:
          description: 'Accepted.

            The request has been accepted.

            '
          headers:
            Location:
              description: 'Location of the existing Application.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
        404:
          $ref: '#/components/responses/NotFound'
      security:
      - OAuth2Security:
        - apim:admin
        - apim:app_import_export
      x-code-samples:
      - lang: Curl
        source: 'curl -k -X DELETE -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" "https://127.0.0.1:9443/api/am/admin/v4/applications/0a043c2b-ee75-4ef3-9e1c-fc2610ccfa8b"'
      operationId: deleteApplicationsByApplicationId
      x-operation-id-source: derived
    put:
      tags:
      - Applications
      summary: Update an Application
      description: This operation can be used to update an application. Upon succesfull you will retrieve the updated application as the response.
      parameters:
      - $ref: '#/components/parameters/applicationId_2'
      - $ref: '#/components/parameters/If-Match'
      requestBody:
        description: 'Application object that needs to be updated

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application_2'
        required: true
      responses:
        200:
          description: 'OK.

            Application updated.

            '
          headers:
            ETag:
              description: 'Entity Tag of the response resource. Used by caches, or in conditional request.

                '
              schema:
                type: string
            Last-Modified:
              description: 'Date and time the resource has been modifed the last time.

                Used by caches, or in conditional requests.

                '
              schema:
                type: string
            Location:
              description: 'The URL of the newly created resource.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application_2'
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
        412:
          $ref: '#/components/responses/PreconditionFailed'
      security:
      - OAuth2Security:
        - apim:subscribe
        - apim:app_manage
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" -H "Content-Type: application/json" -X PUT -d @data.json "https://localhost:9443/api/am/devportal/v3/applications/896658a0-b4ee-4535-bbfa-806c894a4015"'
      operationId: putApplicationsByApplicationId
      x-operation-id-source: derived
    servers:
    - url: https://apis.wso2.com/api/am/admin/v4
  /applications:
    get:
      tags:
      - Applications
      summary: Retrieve/Search Applications
      description: This operation can be used to retrieve list of applications that is belonged to the user associated with the provided access token.
      parameters:
      - $ref: '#/components/parameters/groupId'
      - name: query
        in: query
        description: '**Search condition**.


          You can search for an application by specifying the name as "query" attribute.


          Eg.

          "app1" will match an application if the name is exactly "app1".


          Currently this does not support wildcards. Given name must exactly match the application name.

          '
        schema:
          type: string
      - name: sortBy
        in: query
        schema:
          type: string
          enum:
          - name
          - throttlingPolicy
          - status
      - name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/If-None-Match'
      responses:
        200:
          description: 'OK.

            Application list returned.

            '
          headers:
            ETag:
              description: 'Entity Tag of the response resource.

                Used by caches, or in conditional requests.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationList'
        304:
          description: 'Not Modified.

            Empty body because the client has already the latest version of the requested resource.

            '
          content: {}
        400:
          $ref: '#/components/responses/BadRequest'
        406:
          $ref: '#/components/responses/NotAcceptable'
      security:
      - OAuth2Security:
        - apim:subscribe
        - apim:app_manage
        - apim:app_import_export
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" "https://localhost:9443/api/am/devportal/v3/applications?query=CalculatorApp"'
      operationId: getApplications
      x-operation-id-source: derived
    post:
      tags:
      - Applications
      summary: Create a New Application
      description: This operation can be used to create a new application specifying the details of the application in the payload.
      requestBody:
        description: 'Application object that is to be created.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application_2'
        required: true
      responses:
        201:
          description: 'Created.

            Successful response with the newly created object as entity in the body.

            Location header contains URL of newly created entity.

            '
          headers:
            ETag:
              description: 'Entity Tag of the response resource. Used by caches, or in conditional request

                '
              schema:
                type: string
            Location:
              description: 'Location of the newly created Application.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application_2'
        202:
          description: 'Accepted.

            The request has been accepted.

            '
          headers:
            Location:
              description: 'Location of the newly created Application.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        409:
          $ref: '#/components/responses/Conflict'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
      security:
      - OAuth2Security:
        - apim:subscribe
        - apim:app_manage
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" -H "Content-Type: application/json" -X POST -d @data.json "https://localhost:9443/api/am/devportal/v3/applications"'
      operationId: postApplications
      x-operation-id-source: derived
    servers:
    - url: https://apis.wso2.com/api/am/devportal/v3
  /applications/{applicationId}/reset-throttle-policy:
    post:
      tags:
      - Applications
      summary: Reset Application-Level Throttle Policy
      description: This operation can be used to reset the application-level throttle policy for a specific user.
      parameters:
      - $ref: '#/components/parameters/applicationId_2'
      requestBody:
        description: 'Payload for which the application-level throttle policy needs to be reset

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationThrottleReset'
        required: true
      responses:
        200:
          description: OK. Application-level throttle policy reset successfully
          content: {}
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          description: 'Forbidden.

            The request must be conditional but no condition has been specified.

            '
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
      security:
      - OAuth2Security:
        - apim:app_manage
        - apim:subscribe
      x-code-samples:
      - lang: Curl
        source: 'curl -k \ -H "Authorization: Bearer 80249337-fe7c-3c66-bde6-ed431c144372" \ -H "Content-Type: application/json" -X POST \ -d @payload.json \ "https://localhost:9443/api/am/devportal/v3/application/37dd21cc-631e-4c73-bf73-c59cc7087a63/reset-throttle-policy"'
      operationId: postApplicationsByApplicationIdResetThrottlePolicy
      x-operation-id-source: derived
    servers:
    - url: https://apis.wso2.com/api/am/devportal/v3
components:
  parameters:
    applicationId:
      name: applicationId
      in: path
      description: 'Application UUID

        '
      required: true
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: 'Maximum size of resource array to return.

        '
      schema:
        type: integer
        default: 25
    If-None-Match:
      name: If-None-Match
      in: header
      description: 'Validator for conditional requests; based on the ETag of the formerly retrieved

        variant of the resourec.

        '
      schema:
        type: string
    If-Match:
      name: If-Match
      in: header
      description: 'Validator for conditional requests; based on ETag.

        '
      schema:
        type: string
    groupId:
      name: groupId
      in: query
      description: 'Application Group Id

        '
      schema:
        type: string
    offset:
      name: offset
      in: query
      description: 'Starting point within the complete list of items qualified.

        '
      schema:
        type: integer
        default: 0
    applicationId_2:
      name: applicationId
      in: path
      description: 'Application Identifier consisting of the UUID of the Application.

        '
      required: true
      schema:
        type: string
    requestedTenant:
      name: X-WSO2-Tenant
      in: header
      description: "For cross-tenant invocations, this is used to specify the tenant domain, where the resource need to be\n  retrieved from.\n"
      schema:
        type: string
  schemas:
    WorkflowResponse:
      title: workflow Response
      required:
      - workflowStatus
      type: object
      properties:
        workflowStatus:
          type: string
          description: 'This attribute declares whether this workflow task is approved or rejected.

            '
          example: APPROVED
          enum:
          - CREATED
          - APPROVED
          - REJECTED
          - REGISTERED
        jsonPayload:
          type: string
          description: 'Attributes that returned after the workflow execution

            '
    Error:
      title: Error object returned with 4XX HTTP status
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: integer
          description: Error code
          format: int64
        message:
          type: string
          description: Error message.
        description:
          type: string
          description: 'A detail description about the error message.

            '
        moreInfo:
          type: string
          description: 'Preferably an url with more details about the error.

            '
        error:
          type: array
          description: 'If there are more than one error list them out.

            For example, list out validation errors by each field.

            '
          items:
            $ref: '#/components/schemas/ErrorListItem'
    Application:
      title: Application object with all the application details
      type: object
      properties:
        applicationId:
          type: string
          example: 01234567-0123-0123-0123-012345678901
        name:
          type: string
          example: CalculatorApp
        throttlingPolicy:
          type: string
          example: Unlimited
        description:
          type: string
          example: Sample calculator application
        tokenType:
          type: string
          enum:
          - OAUTH
          - JWT
          description: 'Type of the access token generated for this application.

            **OAUTH:** A UUID based access token which is issued by default.

            **JWT:** A self-contained, signed JWT based access token. **Note:** This can be only used in Microgateway environments.

            '
          default: JWT
          example: JWT
        status:
          type: string
          example: APPROVED
          default: ''
        groups:
          type: array
          items:
            type: string
          example: ''
        subscriptionCount:
          type: integer
        attributes:
          type: object
          additionalProperties:
            type: string
          example: External Reference ID, Billing Tier
        subscriptionScopes:
          type: array
          items:
            $ref: '#/components/schemas/ScopeInfo'
        owner:
          description: 'Application created user

            '
          type: string
          example: admin
    ScopeInfo:
      title: API Scope info object with scope details
      type: object
      properties:
        key:
          type: string
          example: admin_scope
        name:
          type: string
          example: admin scope
        roles:
          type: array
          items:
            type: string
          description: Allowed roles for the scope
          example:
          - manager
          - developer
        description:
          type: string
          description: Description of the scope
    ErrorListItem:
      title: Description of individual errors that may have occurred during a request.
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: 'Description about individual errors occurred

            '
    ConsumerSecret:
      type: object
      properties:
        secretId:
          type: string
          description: Unique identifier for the secret
          example: sec_123456
        secretValue:
          type: string
          description: The actual secret string
          example: '***r3tV@lu3'
        additionalProperties:
          type: object
          description: Additional dynamic properties for the secret creation request.
          additionalProperties:
            type: object
          example:
            expiresAt: 1761568483
            description: pizza application secret
    Application_2:
      title: Application
      required:
      - name
      - throttlingPolicy
      type: object
      properties:
        applicationId:
          type: string
          readOnly: true
          example: 01234567-0123-0123-0123-012345678901
        name:
          maxLength: 100
          minLength: 1
          type: string
          example: CalculatorApp
        throttlingPolicy:
          minLength: 1
          type: string
          example: Unlimited
        description:
          maxLength: 512
          type: string
          example: Sample calculator application
        tokenType:
          type: string
          description: 'Type of the access token generated for this application.


            **OAUTH:** A UUID based access token

            **JWT:** A self-contained, signed JWT based access token which is issued by default.

            '
          example: JWT
          default: JWT
          enum:
          - OAUTH
          - JWT
        status:
          type: string
          readOnly: true
          example: APPROVED
          default: ''
        groups:
          type: array
          example: []
          items:
            type: string
        subscriptionCount:
          type: integer
          readOnly: true
        keys:
          type: array
          readOnly: true
          example: []
          items:
            $ref: '#/components/schemas/ApplicationKey'
        attributes:
          type: object
          additionalProperties:
            type: string
          example: {}
        subscriptionScopes:
          type: array
          example: []
          items:
            $ref: '#/components/schemas/ScopeInfo'
        owner:
          type: string
          description: 'Application created user

            '
          readOnly: true
          example: admin
        hashEnabled:
          type: boolean
          readOnly: true
          example: false
        createdTime:
          type: string
          readOnly: true
          example: 1651555310208
        updatedTime:
          type: string
          readOnly: true
          example: 1651555310208
        visibility:
          type: string
          enum:
          - PRIVATE
          - SHARED_WITH_ORG
    ErrorListItem_2:
      title: Description of individual errors that may have occurred during a request.
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
          description: 'Description about individual errors occurred

            '
    Pagination:
      title: Pagination
      type: object
      properties:
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 10
        total:
          type: integer
          example: 1
        next:
          type: string
          description: 'Link to the next subset of resources qualified.

            Empty if no more resources are to be returned.

            '
          example: ''
        previous:
          type: string
          description: 'Link to the previous subset of resources qualified.

            Empty if current subset is the first subset returned.

            '
          example: ''
    ApplicationToken:
      title: Application token details to invoke APIs
      type: object
      properties:
        accessToken:
          type: string
          description: Access token
          example: 1.2345678901234568E30
        tokenScopes:
          type: array
          description: Valid comma seperated scopes for the access token
          example:
          - default
          - read_api
          - write_api
          items:
            type: string
        validityTime:
          type: integer
          description: Maximum validity time for the access token
          format: int64
          example: 3600
    Error_2:
      title: Error object returned with 4XX HTTP status
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: integer
          format: int64
        message:
          type: string
          description: Error message.
        description:
          type: string
          description: 'A detail description about the error message.

            '
        moreInfo:
          type: string
          description: 'Preferably an url with more details about the error.

            '
        error:
          type: array
          description: 'If there are more than one error list them out.

            For example, list out validation errors by each field.

            '
          items:
            $ref: '#/components/schemas/ErrorListItem_2'
    ApplicationKey:
      title: Application key details
      type: object
      properties:
        keyMappingId:
          type: string
          description: Key Manager Mapping UUID
          readOnly: true
          example: 92ab520c-8847-427a-a921-3ed19b15aad7
        keyManager:
          type: string
          description: Key Manager Name
          example: Resident Key Manager
        consumerKey:
          type: string
          description: Consumer key of the application
          readOnly: true
          example: vYDoc9s7IgAFdkSyNDaswBX7ejoa
        consumerSecret:
          type: string
          description: Consumer secret of the application
          readOnly: true
          example: TIDlOFkpzB7WjufO3OJUhy1fsvAa
        consumerSecrets:
          type: array
          description: A list of all consumer secrets of the application When multiple consumer secrets are enabled
          items:
            $ref: '#/components/schemas/ConsumerSecret'
        supportedGrantTypes:
          type: array
          description: The grant types that are supported by the application
          example:
          - client_credentials
          - password
          items:
            type: string
        callbackUrl:
          type: string
          description: Callback URL
          example: http://sample.com/callback/url
        keyState:
          type: string
          description: Describes the state of the key generation.
          example: APPROVED
        keyType:
          type: string
          description: Describes to which endpoint the key belongs
          example: PRODUCTION
          enum:
          - PRODUCTION
          - SANDBOX
        mode:
          type: string
          description: Describe the which mode Application Mapped.
          example: CREATED
          enum:
          - MAPPED
          - CREATED
        groupId:
          type: string
          description: Application group id (if any).
          example: '2'
        token:
          $ref: '#/components/schemas/ApplicationToken'
        additionalProperties:
          type: object
          properties: {}
          description: additionalProperties (if any).
    ApplicationInfo:
      title: Application info object with basic application details
      type: object
      properties:
        applicationId:
          type: string
          example: 01234567-0123-0123-0123-012345678901
        name:
          type: string
          example: CalculatorApp
        throttlingPolicy:
          type: string
          example: Unlimited
        description:
          type: string
          example: Sample calculator application
        status:
          type: string
          example: APPROVED
          default: ''
        groups:
          type: array
          example: ''
          items:
            type: string
        subscriptionCount:
          type: integer
        attributes:
          type: object
          properties: {}
          example: External Reference ID, Billing Tier
        owner:
          type: string
          example: admin
        tokenType:
          type: string
          example: JWT
        createdTime:
          type: string
          readOnly: true
          example: 1651555310208
        updatedTime:
          type: string
          readOnly: true
          example: 1651555310208
    ApplicationThrottleReset:
      title: Reset application level throttling
      type: object
      properties:
        userName:
          type: string
          description: The username for which the throttle policy needs to be reset
          example: admin
    ApplicationList:
      title: Application List
      type: object
      properties:
        count:
          type: integer
          description: 'Number of applications returned.

            '
          example: 1
        list:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationInfo'
        pagination:
          $ref: '#/components/schemas/Pagination'
  responses:
    BadRequest:
      description: Bad Request. Invalid request or validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            message: Bad Request
            description: Invalid request or validation error
            moreInfo: ''
            error: []
    NotFound:
      description: Not Found. The specified resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 404
            message: Not Found
            description: The specified resource does not exist
            moreInfo: ''
            error: []
    NotAcceptable:
      description: Not Acceptable. The requested media type is not supported.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 406
            message: Not Acceptable
            description: The requested media type is not supported
            moreInfo: ''
            error: []
    UnsupportedMediaType:
      description: Unsupported Media Type. The entity of the request was not in a supported format.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
          example:
            code: 415
            message: Unsupported media type
            description: The entity of the request was not in a supported format
            moreInfo: ''
            error: []
    InternalServerError:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
          example:
            code: 500
            message: Internal Server Error
            description: The server encountered an internal error. Please contact administrator.
            moreInfo: ''
            error: []
    PreconditionFailed:
      description: Precondition Failed. The request has not been performed because one of the preconditions is not met.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
          example:
            code: 412
            message: Precondition Failed
            description: The request has not been performed because one of the preconditions is not met
            moreInfo: ''
            error: []
    Unauthorized:
      description: Unauthorized. The user is not authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
          example:
            code: 401
            message: Unauthorized
            description: The user is not authorized
            moreInfo: ''
            error: []
    Conflict:
      description: Conflict. Specified resource already exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
          example:
            code: 409
            message: Conflict
            description: Specified resource already exists
            moreInfo: ''
            error: []
  securitySchemes:
    OAuth2Security:
      type: oauth2
      flows:
        password:
          tokenUrl: https://localhost:9443/oauth2/token
          scopes:
            openid: Authorize access to user details
            apim:policies_import_export: Export and import policies related operations
            apim:admin: Manage all admin operations
            apim:tier_view: View throttling policies
            apim:tier_manage: Update and delete throttling policies
            apim:admin_tier_view: View throttling policies
            apim:admin_tier_manage: Update and delete throttling policies
            apim:bl_view: View deny policies
            apim:bl_manage: Update and delete deny policies
            apim:mediation_policy_view: View mediation policies
            apim:mediation_policy_create: Create and update mediation policies
            apim:app_owner_change: Retrieve and manage applications
            apim:app_settings_change: Change Application Settings
            apim:app_import_export: Import and export applications related operations
            apim:api_import_export: Import and export APIs related operations
            apim:api_product_import_export: Import and export API Products related operations
            apim:environment_manage: Manage gateway environments
            apim:environment_read: Retrieve gateway environments
            apim:monetization_usage_publish: Retrieve and publish Monetization related usage records
            apim:api_workflow_approve: Manage workflows
            apim:bot_data: Retrieve bot detection data
            apim:tenantInfo: Retrieve tenant related information
            apim:tenant_theme_manage: Manage tenant themes
            apim:admin_operations: Manage API categories and Key Managers related operations
            apim:api_category: Manage API categories
            apim:admin_settings: Retrieve admin settings
            apim:admin_alert_manage: Manage admin alerts
            apim:api_workflow_view: Retrive workflow requests
            apim:scope_manage: Manage system scopes
            apim:role_manage: Manage system roles
            apim:admin_application_view: View Applications
            apim:keymanagers_manage: Manage Key Managers
            apim:api_provider_change: Retrieve and manage applications
            apim:llm_provider_manage: Manage LLM Providers
            apim:gov_policy_read: Retrieve governance policies
            apim:gov_policy_manage: Manage governance policies
            apim:gov_result_read: Retrieve governance results
            apim:gov_rule_read: Retrieve governance rules
            apim:gov_rule_manage: Manage governance rules
            apim:organization_manage: Manage Organizations
            apim:organization_read: Read Organizations
x-refined-from:
- wso2-admin-api.yaml
- wso2-devportal-api.yaml