WSO2 System Scopes API

openapi: 3.2.0
info:
  title: WSO2 API Manager - Admin System Scopes 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: System Scopes
paths:
  /system-scopes/{scopeName}:
    get:
      tags:
      - System Scopes
      summary: Retrieve Scopes for a Particular User
      description: 'This operation will return the scope list of particular user

        In order to get it, we need to pass the userId as a query parameter'
      operationId: systemScopesScopeNameGet
      parameters:
      - name: username
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/scopeName'
      responses:
        200:
          description: 'OK.

            Particular scope exists for the given user.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeSettings'
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
      security:
      - OAuth2Security:
        - apim:admin
        - apim:scope_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/system-scopes/YXBpbTpzdWJzY3JpYmU?username=john"'
  /system-scopes:
    get:
      tags:
      - System Scopes
      summary: Get Role Scope Mappings
      description: This operation is used to get the list of role scope mapping from tenant-conf for the apim admin dashboard
      operationId: systemScopesGet
      responses:
        200:
          description: 'OK.

            The list of role scope mappings are returned.

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

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeList'
        500:
          $ref: '#/components/responses/InternalServerError'
      security:
      - OAuth2Security:
        - apim:scope_manage
        - apim:admin
      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/system-scopes"'
    put:
      tags:
      - System Scopes
      summary: Update Roles For Scope
      description: This operation is used to update the roles for all scopes
      operationId: updateRolesForScope
      requestBody:
        description: 'Scope list object with updated scope to role mappings

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

            Successful response with the newly added roles.

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

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeList'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
      security:
      - OAuth2Security:
        - apim:admin
        - apim:scope_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/system-scopes"'
  /system-scopes/role-aliases:
    get:
      tags:
      - System Scopes
      summary: Retrieve Role Alias Mappings
      description: This operation can be used to retreive role alias mapping
      responses:
        200:
          description: 'OK.

            The list of role mappings are returned.

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

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleAliasList'
        404:
          $ref: '#/components/responses/NotFound'
      security:
      - OAuth2Security:
        - apim:admin
        - apim:scope_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/system-scopes/role-aliases"'
      operationId: getSystemScopesRoleAliases
      x-operation-id-source: derived
    put:
      tags:
      - System Scopes
      summary: Add a New Role Alias
      description: This operation can be used to add a new role alias mapping for system scope roles
      requestBody:
        description: role-alias mapping
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleAliasList'
        required: true
      responses:
        200:
          description: 'OK.

            Role mapping alias returned

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleAliasList'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
      security:
      - OAuth2Security:
        - apim:scope_manage
        - apim:admin
      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/system-scopes/role-aliases"'
      operationId: putSystemScopesRoleAliases
      x-operation-id-source: derived
components:
  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: []
    InternalServerError:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 500
            message: Internal Server Error
            description: The server encountered an internal error. Please contact administrator.
            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: []
  schemas:
    ScopeSettings:
      title: Settings
      type: object
      properties:
        name:
          type: string
          example: apim:subscribe
    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'
    ScopeList:
      title: Scope Role Mapping List
      type: object
      properties:
        count:
          type: integer
          description: 'Number of scopes available for tenant.

            '
          readOnly: true
          example: 60
        list:
          type: array
          items:
            $ref: '#/components/schemas/Scope'
    RoleAliasList:
      title: Role alias list
      type: object
      properties:
        count:
          type: integer
          description: The number of role aliases
          example: 1
        list:
          type: array
          items:
            $ref: '#/components/schemas/RoleAlias'
    RoleAlias:
      title: Role alias
      type: object
      properties:
        role:
          type: string
          description: The original role
          example: Internal/subscriber
        aliases:
          type: array
          description: The role mapping for role alias
          example:
          - Subscriber
          - Internal/subscriber
          items:
            type: string
    Scope:
      title: Scope Role
      type: object
      properties:
        tag:
          type: string
          description: 'Portal name.

            '
          example: publisher
        name:
          type: string
          description: 'Scope name.

            '
          example: apim:api_publish
        description:
          type: string
          description: 'About scope.

            '
          example: Publish API
        roles:
          type: array
          description: 'Roles for the particular scope.

            '
          example:
          - admin
          - Internal/publisher
          items:
            type: string
    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

            '
  parameters:
    scopeName:
      name: scopeName
      in: path
      description: 'Base64 URL encoded value of the scope name to be validated

        '
      required: true
      schema:
        type: string
  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