swagger: '2.0'
######################################################
# Prolog
######################################################
info:
  version: "0.9.0"
  title: "WSO2 Identity Server Scope Endpoint"
  description: |
    This document specifies a **Oauth Scope Endpoint** for WSO2 **Identity Server** .

    It is written with [swagger 2](http://swagger.io/).

  contact:
    name: "WSO2"
    url: "http://wso2.com/products/identity-server/"
    email: "architecture@wso2.com"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

######################################################
# The fixed parts of the URLs of the API
######################################################

# The schemes supported by the API
schemes:
  - https

# The domain of the API.
# This is configured by the customer during deployment.
# The given host is just an example.
host: apis.is.com

# The base path of the API.
# Will be prefixed to all paths.

# if the tenant domain is carbon.super basepath can be /api/identity/oauth2/v0.9 like this too.
basePath: /t/{tenant_domain}/api/identity/oauth2/v0.9

# The following media types can be passed as input in message bodies of the API.
# The actual media type must be specified in the Content-Type header field of the request.
# The default is json, i.e. the Content-Type header is not needed to
# be set, but supporting it serves extensibility.
consumes:
  - application/json

# The following media types may be passed as output in message bodies of the API.
# The media type(s) consumable by the requestor is specified in the Accept header field
# of the corresponding request.
# The actual media type returned will be specfied in the Content-Type header field
# of the of the response.
# The default of the Accept header is json, i.e. there is not needed to
# set the value, but supporting it serves extensibility.
produces:
  - application/json
paths:
  /scope:
    # Endpoint uses to create scope
    post:
      description: |
         This API is used to create scope.
      x-wso2-request: |
        curl -X POST -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '[{"key": "openid", "name": "openid", "description": "openid scope", "bindings": []},{"key": "openid2", "name": "openid2", "description": "openid scope", "bindings": []}]' "https://localhost:9443/api/identity/oauth2/v0.9/scope"

      x-wso2-response: |
        "HTTP/1.1 201 Created"

      summary: |
        Register Scope

      operationId: registerScopes

      # These are the post parameters:
      parameters:
        -
          name: Scope
          in: body
          description: a list of scope with the bindings which to be registered
          required: true
          schema:
            type: array
            items:
              $ref: '#/definitions/Scope'

      responses:
        201:
          description: Successful created
          schema:
            title: key
            type: string
        400:
          description: Bad Request
          schema:
             $ref: '#/definitions/Error'

        500:
          description: Server Error
          schema:
             $ref: '#/definitions/Error'

        409:
          description: Conflict
          schema:
             $ref: '#/definitions/Error'
      tags:
        - Scope Register

    # Endpoint uses to delete list of scopes
    delete:
      description: |
         This API is used to delete list of scopes
      x-wso2-request: |
        curl -X DELETE -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '["key1", "key2"]' "https://localhost:9443/api/identity/oauth2/v0.9/scope"

      x-wso2-response: |
        "HTTP/1.1 201 Deleted"

      operationId: deleteScopes

      summary: |
        Delete list of Scopes

      # These are the post parameters:
      parameters:
        -
          name: Scope
          in: body
          description: a list of scope keys of the scopes which need to get deleted
          required: true
          schema:
            type: array
            items:
              type: string

      responses:
        201:
          description: Successful deleted
          schema:
            title: key
            type: string
        400:
          description: Bad Request
          schema:
             $ref: '#/definitions/Error'

        500:
          description: Server Error
          schema:
             $ref: '#/definitions/Error'

        409:
          description: Conflict
          schema:
             $ref: '#/definitions/Error'
      tags:
        - Scope Delete

    # Endpoint uses to update scope list using PUT
    put:
      description: |
         This API is used to update scope list.
      x-wso2-request: |
        curl -X PUT -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '[{"key": "openid", "name": "openid", "description": "openid scope", "bindings": []}]' "https://localhost:9443/api/identity/oauth2/v0.9/scope"

      x-wso2-response: |
        "HTTP/1.1 201 Updated"

      summary: |
        Update Scope List

      operationId: updateScopes

      # These are the post parameters:
      parameters:
        -
          name: Scope
          in: body
          description: a list of updated scopes
          required: true
          schema:
            type: array
            items:
              $ref: '#/definitions/Scope'

      responses:
        201:
          description: Successful updated
          schema:
            title: key
            type: string
        400:
          description: Bad Request
          schema:
             $ref: '#/definitions/Error'

        500:
          description: Server Error
          schema:
             $ref: '#/definitions/Error'

        409:
          description: Conflict
          schema:
             $ref: '#/definitions/Error'
      tags:
        - Scope Update

    # Endpoint uses to update scope list using PATCH
#    patch:
#      description: |
#         This API is used to update scope list.
#      x-wso2-request: |
#        curl -X PATCH -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '[{"key": "openid", "bindings": []}]' "https://localhost:9443/api/identity/oauth2/v0.9/scope"
#
#      x-wso2-response: |
#        "HTTP/1.1 201 Updated"
#
#      summary: |
#        Update Scope List
#
#      operationId: updateScopeListPATCH
#
#      # These are the post parameters:
#      parameters:
#        -
#          name: Scope
#          in: body
#          description:
#          required: true
#          schema:
#            type: array
#            items:
#              $ref: '#/definitions/Scope'
#
#      responses:
#        201:
#          description: Successful updated
#          schema:
#            title: key
#            type: string
#        400:
#          description: Bad Request
#          schema:
#             $ref: '#/definitions/Error'
#
#        500:
#          description: Server Error
#          schema:
#             $ref: '#/definitions/Error'
#
#        409:
#          description: Conflict
#          schema:
#             $ref: '#/definitions/Error'
#      tags:
#        - Scope Update

    # Endpoint uses to get all the available scopes
    get:
      description: |
         This API is used to get all the available scopes.
      x-wso2-request: |
        curl -X GET -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{}' "https://localhost:9443/api/identity/oauth2/v0.9/scope?filter=maxResults+Eq+100"

      x-wso2-response: |
        [{"key": "openid", "name": "openid", "description": "openid scope", "bindings": []}]

      summary: |
        Get all available Scopes

      operationId: getScopes

      # These are the post parameters:
      parameters:
        -
          name: filter
          in: query
          description: filter when retrieving all available scopes
          required: false
          type: string

      responses:
        201:
          description: Successful Retrieved
          schema:
            type: array
            items:
              $ref: '#/definitions/Scope'
        400:
          description: Bad Request
          schema:
             $ref: '#/definitions/Error'

        500:
          description: Server Error
          schema:
             $ref: '#/definitions/Error'

        409:
          description: Conflict
          schema:
             $ref: '#/definitions/Error'
      tags:
        - Scope Retrieve

     # Endpoint uses to get scopes by binding/s
  /scope/by-bindings:
     get:
       description: |
         This API is used to get scopes by binding/s.
       x-wso2-request: |
         curl -X GET -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{"bindings": ["role1", "role2"]}' "https://localhost:9443/api/identity/oauth2/v0.9/scope/by-bindings"

       x-wso2-response: |
         [{"key": "openid", "name": "openid", "description": "openid scope", "bindings": []}]

       summary: |
         Get Scopes by binding/s

       operationId: getScopesByBindings

       parameters:
         -
           name: bindings
           in: body
           description: list of bindings to be used when filtering scopes by bindings
           required: true
           schema:
             type: array
             items:
               type: string

       responses:
         201:
           description: Successful Retrieved
           schema:
             type: array
             items:
               $ref: '#/definitions/Scope'
         400:
           description: Bad Request
           schema:
             $ref: '#/definitions/Error'

         500:
           description: Server Error
           schema:
             $ref: '#/definitions/Error'

         409:
           description: Conflict
           schema:
             $ref: '#/definitions/Error'
       tags:
         - Scope Retrieve

######################################################################
  # Endpoint uses to get all the available scope keys
  /scope/keys:
    get:
      description: |
         This API is used to get all the available scope keys.
      x-wso2-request: |
        curl -X GET -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{}' "https://localhost:9443/api/identity/oauth2/v0.9/scope/keys"

      x-wso2-response: |
        ["key1", "key2"]

      summary: |
        Get all available Scope Keys

      operationId: getScopeKeys

      responses:
        201:
          description: Successful Retrieved
          schema:
            type: array
            items:
              type: string
        400:
          description: Bad Request
          schema:
             $ref: '#/definitions/Error'

        500:
          description: Server Error
          schema:
             $ref: '#/definitions/Error'

        409:
          description: Conflict
          schema:
             $ref: '#/definitions/Error'
      tags:
        - Scope Retrieve

    # Endpoint uses to get scope key list by binding/s
  /scope/keys/by-bindings:
    get:
      description: |
         This API is used to get a scope key list by binding/s.
      x-wso2-request: |
        curl -X GET -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{"bindings": ["role1", "role2"]}' "https://localhost:9443/api/identity/oauth2/v0.9/scope/keys/by-bindings"

      x-wso2-response: |
        ["key1", "key2"]

      summary: |
        Get Scope Key list by binding/s

      operationId: getScopeKeysByBindings

      # These are the post parameters:
      parameters:
        -
          name: bindings
          in: body
          description: list of bindings to be used when filtering scope keys by bindings
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        201:
          description: Successful Retrieved
          schema:
            type: array
            items:
              type: string
        400:
          description: Bad Request
          schema:
             $ref: '#/definitions/Error'

        500:
          description: Server Error
          schema:
             $ref: '#/definitions/Error'

        409:
          description: Conflict
          schema:
             $ref: '#/definitions/Error'
      tags:
        - Scope Retrieve

  # Endpoint uses to get scope by scope key
  /scope/{scope_key}:
    get:
      description: |
         This API is used to get a scope by given scope key.
      x-wso2-request: |
        curl -X GET -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{}' "https://localhost:9443/api/identity/oauth2/v0.9/scope/openid"

      x-wso2-response: |
        {"key": "openid", "name": "openid", "description": "openid scope", "bindings": []}

      summary: |
        Get a Scope by Scope Key

      operationId: getScopeByKey

      # These are the post parameters:
      parameters:
        -
          name: scope_key
          in: path
          description: scope key of the scope which the details to be retrieved
          required: true
          schema:
            type: string

      responses:
        201:
          description: Successful Retrieved
          schema:
            $ref: '#/definitions/Scope'
        400:
          description: Bad Request
          schema:
             $ref: '#/definitions/Error'

        500:
          description: Server Error
          schema:
             $ref: '#/definitions/Error'

        409:
          description: Conflict
          schema:
             $ref: '#/definitions/Error'
      tags:
        - Scope Retrieve

    # Endpoint uses to delete scope by scope key
    delete:
      description: |
         This API is used to delete scope by scope key.
      x-wso2-request: |
        curl -X DELETE -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{}' "https://localhost:9443/api/identity/oauth2/v0.9/scope/openid"

      x-wso2-response: |
        "HTTP/1.1 201 Deleted"

      summary: |
        Delete Scope

      operationId: deleteScopeByKey

      # These are the post parameters:
      parameters:
        -
          name: scope_key
          in: path
          description: scope key of the scope which need to get deleted
          required: false
          type: string

      responses:
        201:
          description: Successful deleted
          schema:
            title: key
            type: string
        400:
          description: Bad Request
          schema:
             $ref: '#/definitions/Error'

        500:
          description: Server Error
          schema:
             $ref: '#/definitions/Error'

        409:
          description: Conflict
          schema:
             $ref: '#/definitions/Error'
      tags:
        - Scope Delete

    # Endpoint uses to update a scope using scope key
    put:
      description: |
         This API is used to update a scope.
      x-wso2-request: |
        curl -X PUT -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{"key": "openid", "name": "openid", "description": "openid scope", "bindings": []}' "https://localhost:9443/api/identity/oauth2/v0.9/scope/openid"

      x-wso2-response: |
        "HTTP/1.1 201 Updated"

      summary: |
        Update a Scope

      operationId: updateScopeByKey

      # These are the post parameters:
      parameters:
        -
          name: Scope
          in: body
          description: updated scope
          required: true
          schema:
            $ref: '#/definitions/Scope'
        -
          name: scope_key
          in: path
          description: scope key of the scope which need to get updated
          required: false
          type: integer

      responses:
        201:
          description: Successful updated
          schema:
            title: key
            type: string
        400:
          description: Bad Request
          schema:
             $ref: '#/definitions/Error'

        500:
          description: Server Error
          schema:
             $ref: '#/definitions/Error'

        409:
          description: Conflict
          schema:
             $ref: '#/definitions/Error'
      tags:
        - Scope Update

    # Endpoint uses to update a scope using PATCH
#    patch:
#      description: |
#         This API is used to update a scope.
#      x-wso2-request: |
#        curl -X PATCH -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{"key": "openid", "bindings": []}' "https://localhost:9443/api/identity/oauth2/v0.9/scope/ids/1"
#
#      x-wso2-response: |
#        "HTTP/1.1 201 Updated"
#
#      summary: |
#        Update a Scope
#
#      operationId: updateScopePATCH
#
#      # These are the post parameters:
#      parameters:
#        -
#          name: Scope
#          in: body
#          description:
#          required: true
#          schema:
#            $ref: '#/definitions/Scope'
#        -
#          name: scope_id
#          in: path
#          description:
#          required: false
#          type: integer
#
#      responses:
#        201:
#          description: Successful updated
#          schema:
#            title: key
#            type: string
#        400:
#          description: Bad Request
#          schema:
#             $ref: '#/definitions/Error'
#
#        500:
#          description: Server Error
#          schema:
#             $ref: '#/definitions/Error'
#
#        409:
#          description: Conflict
#          schema:
#             $ref: '#/definitions/Error'
#      tags:
#        - Scope Update

definitions:
#-----------------------------------------------------
# The Scope Object
#-----------------------------------------------------
  Scope:
    type: object
    properties:
      key:
        type: string
      name:
        type: string
      description:
        type: string
      bindings:
        type: array
        items:
          type: string

#-----------------------------------------------------
# The Error Response object
#-----------------------------------------------------
  Error:
    type: object
    properties:
      code:
        type: string
      message:
        type: string
      description:
        type: string