WSO2 Key Manager (Individual) API

openapi: 3.2.0
info:
  title: WSO2 API Manager - Admin Key Manager (Individual) API
  description: This document specifies a **RESTful API** for WSO2 **API Manager** - **Admin Portal**.
  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: v4
servers:
- url: https://apis.wso2.com/api/am/admin/v4
tags:
- name: Key Manager (Individual)
paths:
  /key-managers/{keyManagerId}:
    get:
      tags:
      - Key Manager (Individual)
      summary: Get a Key Manager Configuration
      description: Retrieve a single Key Manager Configuration. We should provide the Id of the KeyManager as a path parameter.
      parameters:
      - $ref: '#/components/parameters/keyManagerId'
      responses:
        200:
          description: 'OK.

            KeyManager Configuration returned

            '
          headers:
            Content-Type:
              description: 'The content type of the body.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyManager'
        404:
          $ref: '#/components/responses/NotFound'
        406:
          $ref: '#/components/responses/NotAcceptable'
      security:
      - OAuth2Security:
        - apim:admin
        - apim:admin_operations
        - apim:keymanagers_manage
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" "https://127.0.0.1:9443/api/am/admin/v4/key-managers/8d263942-a6df-4cc2-a804-7a2525501450"'
      operationId: getKeyManagersByKeyManagerId
      x-operation-id-source: derived
    put:
      tags:
      - Key Manager (Individual)
      summary: Update a Key Manager
      description: Update a Key Manager by keyManager id
      parameters:
      - $ref: '#/components/parameters/keyManagerId'
      requestBody:
        description: 'Key Manager object with updated information

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

            Label updated.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyManager'
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
      security:
      - OAuth2Security:
        - apim:admin
        - apim:admin_operations
        - apim:keymanagers_manage
      x-code-samples:
      - lang: Curl
        source: 'curl -k -X PUT -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" -H "Content-Type: application/json" -d @data.json "https://127.0.0.1:9443/api/am/admin/v4/key-managers/8d263942-a6df-4cc2-a804-7a2525501450"'
      operationId: putKeyManagersByKeyManagerId
      x-operation-id-source: derived
    delete:
      tags:
      - Key Manager (Individual)
      summary: Delete a Key Manager
      description: Delete a Key Manager by keyManager id
      parameters:
      - $ref: '#/components/parameters/keyManagerId'
      responses:
        200:
          description: 'OK.

            Key Manager successfully deleted.

            '
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
      security:
      - OAuth2Security:
        - apim:admin
        - apim:admin_operations
      x-code-samples:
      - lang: Shell
        source: 'curl -k -X DELETE -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" "https://127.0.0.1:9443/api/am/admin/v2/global-key-managers/8d263942-a6df-4cc2-a804-7a2525501450"'
      operationId: deleteKeyManagersByKeyManagerId
      x-operation-id-source: derived
  /key-managers/{keyManagerId}/api-usages:
    get:
      tags:
      - Key Manager (Individual)
      summary: Retrieve Key Manager Usages (APIs)
      description: 'Retrieves a list of APIs that are specifically utilizing the Key Manager identified by the provided ID.

        The Key Manager ID should be provided as a path parameter.'
      parameters:
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/keyManagerId'
      responses:
        200:
          description: 'OK.

            KeyManager API usages returned.

            '
          headers:
            Content-Type:
              description: 'The content type of the body.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyManagerAPIUsages'
        404:
          $ref: '#/components/responses/NotFound'
        406:
          $ref: '#/components/responses/NotAcceptable'
      security:
      - OAuth2Security:
        - apim:admin
        - apim:admin_operations
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" "https://127.0.0.1:9443/api/am/admin/v4/key-managers/8d263942-a6df-4cc2-a804-7a2525501450/api-usages"'
      operationId: getKeyManagersByKeyManagerIdApiUsages
      x-operation-id-source: derived
  /key-managers/{keyManagerId}/app-usages:
    get:
      tags:
      - Key Manager (Individual)
      summary: Retrieve Key Manager Usages (Appilcations)
      description: 'Retrieves a list of Applications that are specifically utilizing the Key Manager identified by the provided ID.

        The Key Manager ID should be provided as a path parameter.'
      parameters:
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/keyManagerId'
      responses:
        200:
          description: 'OK.

            KeyManager application usages returned.

            '
          headers:
            Content-Type:
              description: 'The content type of the body.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyManagerAppUsages'
        404:
          $ref: '#/components/responses/NotFound'
        406:
          $ref: '#/components/responses/NotAcceptable'
      security:
      - OAuth2Security:
        - apim:admin
        - apim:admin_operations
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" "https://127.0.0.1:9443/api/am/admin/v4/key-managers/8d263942-a6df-4cc2-a804-7a2525501450/app-usages"'
      operationId: getKeyManagersByKeyManagerIdAppUsages
      x-operation-id-source: derived
components:
  parameters:
    offset:
      name: offset
      in: query
      description: 'Starting point within the complete list of items qualified.

        '
      schema:
        type: integer
        default: 0
    limit:
      name: limit
      in: query
      description: 'Maximum size of resource array to return.

        '
      schema:
        type: integer
        default: 25
    keyManagerId:
      name: keyManagerId
      in: path
      description: 'Key Manager UUID

        '
      required: true
      schema:
        type: string
  schemas:
    APIInfoKeyManager:
      type: object
      properties:
        id:
          type: string
          description: The ID of the API.
        type:
          type: string
          description: The type of the entry (e.g., "API").
        name:
          type: string
          description: The name of the API.
        transportType:
          type: string
          description: The transport type of the API.
        description:
          type:
          - string
          - 'null'
          description: The description of the API.
        context:
          type: string
          description: The context of the API.
        version:
          type: string
          description: The version of the API.
        provider:
          type: string
          description: The provider of the API.
        status:
          type: string
          description: The status of the API.
        thumbnailUri:
          type:
          - string
          - 'null'
          description: The URI of the thumbnail of the API.
        advertiseOnly:
          type: boolean
          description: Indicates if the API is advertised only.
        keyManagerEntry:
          type: string
          description: The key manager entry related to the API.
      required:
      - id
      - name
      - version
      - provider
    KeyManagerAppUsages:
      title: Key Manager Application Usages.
      required:
      - applicationCount
      - applications
      type: object
      properties:
        applicationCount:
          type: integer
          description: The total count of applications.
        applications:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationInfoKeyManager'
    ApplicationInfoKeyManager:
      type: object
      properties:
        name:
          type: string
          description: The name of the application.
        uuid:
          type: string
          description: The UUID of the application.
        organizationId:
          type:
          - string
          - 'null'
          description: The ID of the organization to which the application belongs.
        owner:
          type: string
          description: The owner of the application.
        organization:
          type: string
          description: The organization of the application.
      required:
      - name
      - uuid
      - owner
      - organization
    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'
    TokenValidation:
      title: Token handling Configuration
      type: object
      properties:
        id:
          type: integer
        enable:
          type: boolean
          example: false
          default: true
        type:
          type: string
          enum:
          - REFERENCE
          - JWT
          - CUSTOM
        value:
          type: object
          properties: {}
    KeyManagerEndpoint:
      title: Key Manager Endpoint.
      required:
      - name
      - value
      type: object
      properties:
        name:
          type: string
          example: token_endpoint
        value:
          type: string
          example: https://localhost:9443/oauth2/token
    ClaimMappingEntry:
      title: Claim Mapping Configuration
      type: object
      properties:
        remoteClaim:
          type: string
          example: http://idp.org/username
        localClaim:
          type: string
          example: http://wso2.org/username
    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

            '
    KeyManagerAPIUsages:
      title: Key Manager API Usages.
      required:
      - apiCount
      - apis
      type: object
      properties:
        apiCount:
          type: integer
          description: The total count of APIs.
        apis:
          type: array
          items:
            $ref: '#/components/schemas/APIInfoKeyManager'
    KeyManager:
      title: Key Manager
      required:
      - name
      - type
      type: object
      properties:
        id:
          type: string
          readOnly: true
          example: 01234567-0123-0123-0123-012345678901
        name:
          maxLength: 100
          minLength: 1
          type: string
          example: WSO2 Identity Server
        displayName:
          maxLength: 100
          type: string
          description: 'display name of Key Manager to  show in UI

            '
          example: WSO2 Identity Server
        type:
          maxLength: 45
          minLength: 1
          type: string
          example: WSO2-IS
        description:
          maxLength: 256
          type: string
          example: This is a key manager for Developers
        wellKnownEndpoint:
          type: string
          description: 'Well-Known Endpoint of Identity Provider.

            '
          example: ''
        introspectionEndpoint:
          type: string
          example: https://localhost:9444/oauth2/introspect
          deprecated: true
        clientRegistrationEndpoint:
          type: string
          example: https://localhost:9444/keymanager-operations/dcr/register
          deprecated: true
        tokenEndpoint:
          type: string
          example: https://localhost:9444/oauth2/token
          deprecated: true
        displayTokenEndpoint:
          type: string
          example: https://localhost:9444/oauth2/token
          deprecated: true
        revokeEndpoint:
          type: string
          example: https://localhost:9444/oauth2/revoke
          deprecated: true
        displayRevokeEndpoint:
          type: string
          example: https://localhost:9444/oauth2/revoke
          deprecated: true
        userInfoEndpoint:
          type: string
          example: https://localhost:9444/oauth2/userinfo?schema=openid
          deprecated: true
        authorizeEndpoint:
          type: string
          example: https://localhost:9444/oauth2/authorize
          deprecated: true
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/KeyManagerEndpoint'
        certificates:
          type: object
          properties:
            type:
              type: string
              enum:
              - JWKS
              - PEM
            value:
              type: string
        issuer:
          type: string
          example: https://localhost:9444/services
        alias:
          type: string
          description: 'The alias of Identity Provider.

            If the tokenType is EXCHANGED, the alias value should be inclusive in the audience values of the JWT token

            '
          example: https://localhost:9443/oauth2/token
        scopeManagementEndpoint:
          type: string
          example: https://wso2is.com:9444/api/identity/oauth2/v1.0/scopes
          deprecated: true
        availableGrantTypes:
          type: array
          items:
            type: string
            example: client_credentials
        enableTokenGeneration:
          type: boolean
          example: true
        enableTokenEncryption:
          type: boolean
          example: false
          default: false
        enableTokenHashing:
          type: boolean
          example: false
          default: false
        enableMapOAuthConsumerApps:
          type: boolean
          example: false
          default: false
        enableOAuthAppCreation:
          type: boolean
          example: false
          default: false
        enableSelfValidationJWT:
          type: boolean
          example: true
          default: true
        claimMapping:
          type: array
          items:
            $ref: '#/components/schemas/ClaimMappingEntry'
        consumerKeyClaim:
          type: string
          example: azp
        scopesClaim:
          type: string
          example: scp
        tokenValidation:
          type: array
          items:
            $ref: '#/components/schemas/TokenValidation'
        enabled:
          type: boolean
          example: true
        global:
          type: boolean
          example: true
        additionalProperties:
          type: object
          properties: {}
          example:
            self_validate_jwt: true
            Username: admin
            Password: admin
        permissions:
          type: object
          properties:
            permissionType:
              type: string
              example: ALLOW
              default: PUBLIC
              enum:
              - PUBLIC
              - ALLOW
              - DENY
            roles:
              type: array
              items:
                type: string
                example: Internal/subscriber
        tokenType:
          type: string
          description: The type of the tokens to be used (exchanged or without exchanged). Accepted values are EXCHANGED, DIRECT and BOTH.
          example: EXCHANGED
          default: DIRECT
          enum:
          - EXCHANGED
          - DIRECT
          - BOTH
        allowedOrganizations:
          type: array
          items:
            type: string
  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: []
  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