openapi: 3.0.0
info:
  description: |
    This is the RESTful API for OIDC Scope management related operations in WSO2 Identity Server.
  version: "1.0.0-oas3"
  title:  WSO2 Identity Server - OIDC Scope Management API
  termsOfService: 'http://swagger.io/terms/'
  contact:
    name: "WSO2 Identity Server"
    url: "https://wso2.com/identity-and-access-management"
    email: "architecture@wso2.org"
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

servers:
  - url: 'https://localhost:9443/t/{tenant-domain}/api/server/v1'
    variables:
      tenant-domain:
        enum:
          - carbon.super
        default: carbon.super

# The base path of the OIDC scope management API.
# If the tenant domain is carbon.super then basepath can be /api/server/v1
# basePath: /t/{tenant-domain}/api/server/v1/

paths:
  /oidc/scopes:
    get:
      tags:
        - OIDC Scope Endpoint
      summary: Retrieves the list of scopes
      operationId: getScopes
      description: This REST API can be used to get details of the available scopes.<br>	
        <b>Permission required:</b> <br>	
              * /permission/admin/manage/identity/applicationmgt/view <br>	
        <b>Scope required:</b> <br>	
              * internal_application_mgt_view
      security:
        - BasicAuth: []
        - OAuth2: []
      responses:
        200:
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Scope'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
    post:
      tags:
        - OIDC Scope Endpoint
      summary: Add a new OIDC Scope
      description: This REST API can be used to add a new OIDC scope. <br>	
        <b>Permission required:</b> <br>	
              * /permission/admin/manage/identity/applicationmgt/create <br>	
        <b>Scope required:</b> <br>	
              * internal_application_mgt_create
      operationId: addScope
      security:
        - BasicAuth: []
        - OAuth2: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Scope'
      responses:
        201:
          $ref: '#/components/responses/Created'
        400:
          $ref: '#/components/responses/InvalidInput'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        409:
          $ref: '#/components/responses/Conflict'
        500:
          $ref: '#/components/responses/ServerError'
  /oidc/scopes/{id}:
    get:
      tags:
        - OIDC Scope Endpoint
      summary: Get a scope
      operationId: getScope
      description: This REST API can be used to get the scope. <br>	
        <b>Permission required:</b> <br>	
              * /permission/admin/manage/identity/applicationmgt/view <br>	
        <b>Scope required:</b> <br>	
              * internal_application_mgt_view
      security:
        - BasicAuth: []
        - OAuth2: []
      parameters:
        - name: id
          in: path
          description: scope name as the id
          required: true
          schema:
            type: string
            example: scope1
      responses:
        200:
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scope'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
    put:
      tags:
        - OIDC Scope Endpoint
      summary: Update an OIDC Scope
      description: This API can be used to update an existing OIDC scope. <br>	
        <b>Permission required:</b> <br>	
              * /permission/admin/manage/identity/applicationmgt/update <br>	
        <b>Scope required:</b> <br>	
              * internal_application_mgt_update
      operationId: updateScope
      security:
        - BasicAuth: []
        - OAuth2: []
      parameters:
        - name: id
          in: path
          description: scope name as the ID
          required: true
          schema:
            type: string
            example: scope1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScopeUpdateRequest'
      responses:
        200:
          description: OK.
        400:
          $ref: '#/components/responses/InvalidInput'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - OIDC Scope Endpoint
      summary: Delete an OIDC Scope
      description: This API can be used to delete an existing OIDC scope. <br>	
        <b>Permission required:</b> <br>	
              * /permission/admin/manage/identity/applicationmgt/delete <br>	
        <b>Scope required:</b> <br>	
              * internal_application_mgt_delete
      operationId: deleteScope
      security:
        - BasicAuth: []
        - OAuth2: []
      parameters:
        - name: id
          in: path
          description: scope name as the ID
          required: true
          schema:
            type: string
            example: scope1
      responses:
        204:
          $ref: '#/components/responses/NoContent'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        500:
          $ref: '#/components/responses/ServerError'

components:
  responses:
    NoContent:
      description: No Content.
    BadRequest:
      description: Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized.
    Forbidden:
      description: Resource Forbidden.
    NotFound:
      description: Resource Not Found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InvalidInput:
      description: Invalid input request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: Scope already Exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Created:
      description: Created
      headers:
        Set-Cookie:
          description: Location of the newly created scope
          schema:
            type: string
            format: uri
            example: https://apis.is.com/t/wso2.com/api/server/v1/oidc/scopes/Scope1
  schemas:
    Scope:
      type: object
      required:
        - name
        - displayName
        - claims
      properties:
        name:
          type: string
          example: Scope1
        displayName:
          type: string
          example: scope1
        description:
          type: string
          example: "Sample scope one"
        claims:
          type: array
          items:
            type: string
          example: [birthdate,gender]
    ScopeUpdateRequest:
      type: object
      required:
        - displayName
        - claims
      properties:
        displayName:
          type: string
          example: scopeOne
        description:
          type: string
          example: "Sample updated scope one"
        claims:
          type: array
          items:
            type: string
          example: [birthdate,gender,age]
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: 'AAA-00000'
        message:
          type: string
          example: 'Some Error Message'
        description:
          type: string
          example: 'Some Error Description'
        traceId:
          type: string
          example: 'e0fbcfeb-3617-43c4-8dd0-7b7d38e13047'
