openapi: 3.0.0
info:
  title: IUDX-AAA-Server
  version: 5.5.0
  description: 'API specification for IUDX AAA Server. These APIs are used by users manage tokens, policy etc. These APIs requires valid token or client details for authentication.'
  license:
    name: Apache 2.0
  contact:
    name: For support contact IUDX Team at
    email: support@iudx.org.in
servers:
  - url: 'https://cos.iudx.org.in'
    description: Production
  - url: 'https://authvertx.iudx.io'
    description: Development
paths:
  /auth/v1/token:
    parameters: []
    post:
      summary: Create Token
      operationId: post-auth-v1-token
      responses:
        '200':
          description: Access token has been successfully generated upon required validation and authentication.
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: object
                    properties:
                      accessToken:
                        type: string
                        minLength: 1
                      expiry:
                        type: number
                      server:
                        type: string
                        minLength: 1
                    required:
                      - accessToken
                      - expiry
                      - server
                required:
                  - type
                  - title
                  - results
                x-examples:
                  example-1:
                    type: 'urn:dx:as:Success'
                    title: Token created
                    results:
                      accessToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJzdWIiOiIzNDliNGI1NS0wMjUxLTQ5MGUtYmVlOS0wMGYzYTVkM2U2NDMiLCJpc3MiOiJhdXRoLnRlc3QuY29tIiwiYXVkIjoiZm9vYmFyLml1ZHguaW8iLCJleHAiOjE2MjY4MzY3ODQsImlhdCI6MTYyNjc5MzU4NCwiaWlkIjoicmc6ZXhhbXBsZS5jb20vNzllN2JmYTYyZmFkNmM3NjViYWM2OTE1NGMyZjI0Yzk0Yzk1MjIwYS9yZXNvdXJjZS1ncm91cCIsInJvbGUiOiJjb25zdW1lciIsImNvbnMiOnt9fQ.eAWKamrRdV4c1MPuoLU6j0bWB6iiM_of5F3LA-_DZGhyu_6aFP4cmCI1Y3ZN2ZRklOSGcrL5aHC8Ccga6dtTrg
                      expiry: 1626836784
                      server: foobar.iudx.io
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Token created
                    results:
                      accessToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJzdWIiOiIzNDliNGI1NS0wMjUxLTQ5MGUtYmVlOS0wMGYzYTVkM2U2NDMiLCJpc3MiOiJhdXRoLnRlc3QuY29tIiwiYXVkIjoiZm9vYmFyLml1ZHguaW8iLCJleHAiOjE2MjY4MzY3ODQsImlhdCI6MTYyNjc5MzU4NCwiaWlkIjoicmc6ZXhhbXBsZS5jb20vNzllN2JmYTYyZmFkNmM3NjViYWM2OTE1NGMyZjI0Yzk0Yzk1MjIwYS9yZXNvdXJjZS1ncm91cCIsInJvbGUiOiJjb25zdW1lciIsImNvbnMiOnt9fQ.eAWKamrRdV4c1MPuoLU6j0bWB6iiM_of5F3LA-_DZGhyu_6aFP4cmCI1Y3ZN2ZRklOSGcrL5aHC8Ccga6dtTrg
                      expiry: 1626836784
                      server: foobar.iudx.io
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
        '400':
          description: Generally for missing or invalid payload details.
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  detail:
                    type: string
                    minLength: 1
                required:
                  - type
                  - title
                  - detail
              examples:
                Invalid Role:
                  value:
                    type: 'urn:dx:as:InvalidRole'
                    title: Role not defined
                    detail: Role not defined
        '401':
          description: |-
            - Unauthorized - `token` invalid/expired
            - Unauthorized - `clientId` & `clientSecret` invalid/not match
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Missing Authentication Details:
                  value:
                    type: 'urn:dx:as:MissingAuthenticationToken'
                    title: Missing auth details
                    detail: Missing auth details
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
        '403':
          description: |-
            - User does not have the correct role for the request
            - APD verification failed
            - The user is required to interact with the APD 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                APD needs interaction:
                  value:
                    type: 'urn:dx:as:MissingInformation'
                    title: APD interaction required
                    detail: The APD requires extra information to grant access. Please use the apdToken and visit the link to interact with the APD
                    context:
                      apdToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJzdWIiOiJmY2JlY2QxOC0yZWNiLTQwNjYtOGE5ZS1mMDczYWFjYmU1NzkiLCJpc3MiOiJhdXRodmVydHguaXVkeC5pbyIsImF1ZCI6ImF1dGhkZXYuaXVkeC5pbyIsImV4cCI6MTY0ODg0MzEwNCwiaWF0IjoxNjQ4Nzk5OTA0LCJzaWQiOiI5ZGQ2NjNlZS02NWExLTQ4ZTctYTJiMC0wNTQwMmY5ZjlkOWYiLCJsaW5rIjoiYXV0aGRldi5pdWR4LmlvIn0.lP3Dn7aroXqVUdp0fbTh1uhrnjwo5Yx3l1lKorEIKhjzZivgBWkflbVN9Lly0yq5gefvYYXgf01nxmU3QNA2EQ
                      expiry: 1648843104
                      server: authdev.iudx.io
                      link: authdev.iudx.io
                APD policy verification failed (deny):
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Policy evaluation failed
                    detail: 'Not allowed, please contact APD Admin'
                No valid policy found:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Policy evaluation failed
                    detail: policy not found
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 4000
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
        - schema:
            type: string
            format: uuid
            minLength: 36
            maxLength: 36
            pattern: '^[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12}$'
          in: header
          name: clientId
          description: AAA Client ID
        - schema:
            type: string
            maxLength: 40
            pattern: '^[0-9a-f]{40}$'
            minLength: 40
            example: 73b66ab55ba4d07ea487310679aa0689b4bd2c9d
          in: header
          description: AAA Client Secret
          name: clientSecret
        - schema:
            type: string
            format: uuid
            minLength: 36
            maxLength: 36
            pattern: '^[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12}$'
          in: header
          name: delegationId
          description: Delegation ID obtained from GET /delegations (in case delegate wants a token)
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                itemId:
                  type: string
                  minLength: 1
                  pattern: '^[a-zA-Z0-9_\-\.]+$'
                  maxLength: 100
                itemType:
                  type: string
                  enum:
                    - resource_server
                    - resource
                    - resource_group
                    - cos  
                role:
                  type: string
                  enum:
                    - provider
                    - delegate
                    - consumer
                    - admin
                    - cos_admin  
                context:
                  type: object
              required:
                - itemId
                - itemType
                - role
            examples:
              Consumer requesting resource group:
                value:
                  itemId: a007f760-8580-4401-81c1-b123da3de06f
                  itemType: resource_group
                  role: consumer
              Consumer requesting resource server (for access to public resources):
                value:
                  itemId: rs.iudx.org.in
                  itemType: resource_server
                  role: consumer
              Consumer requesting resource:
                value:
                  itemId: 31b3da3a-84da-4923-b425-a9c5469c169f
                  itemType: resource
                  role: consumer
              Provider requesting resource group:
                value:
                  itemId: a007f760-8580-4401-81c1-b123da3de06f
                  itemType: resource_group
                  role: provider
              Delegate requesting for resource:
                value:
                  itemId: 31b3da3a-84da-4923-b425-a9c5469c169f
                  itemType: resource
                  role: delegate
              Admin of RS requesting resource server:
                value:
                  itemId: rs.iudx.org.in
                  itemType: resource_server
                  role: admin
              Identity token for resource server as provider:
                value:
                  itemId: rs.iudx.org.in
                  itemType: resource_server
                  role: provider
              Identity token for COS Admin for COS:
                value:
                  itemId: cos.iudx.org.in
                  itemType: cos
                  role: cos_admin
              Requesting resource with context object in body:
                value:
                  itemId: a007f760-8580-4401-81c1-b123da3de06f
                  itemType: resource_group
                  role: consumer
                  context:
                    accessId: 1e5aad64-102c-4688-892f-c6a1f5f4d476
                    accessType: PERMANENT_ACCESS
        description: |-
          - `itemId` : the string value of the id of the resource
            - e.g. `31b3da3a-84da-4923-b425-a9c5469c169f`
          - `itemType` : the kind of item the desired resource is
          - `role` : the role as which the user wants to get token for
          - `context` : a JSON object containing any extra information. The user may use this field to convey information to an APD in case the requested resource is backed by an APD policy
        required: true
      description: |
        Request for a JWT (token). One can generate token using either by providing token header or providing clientId and clientSecret in the header. 

        **NOTE : Either the JWT token in the `Authorization` header or `clientId`+`clientSecret` headers are required, not both**

        # Identity Token
        An Identity token is used by a user to identify themself to a resource server or APD.
          - Valid item types - `resource_server`, `cos` in case of COS admin
          - Item ID - URL of the resource server or COS
          
        ## Conditions    
          - If role is `admin`, the user must own/be the admin of the resource server.
          - If role is `cos_admin`, the user must be the COS Admin and the `itemId` must be the COS URL.
          - For any other role, the user must have the role for the particular resource server. 
          - Users can be permitted to obtain identity tokens with the `admin` role if required.**
              
        # Access Token
        An Access token is used to gain access to an Item on a resource server.

          ## Tokens for providers
           - Valid item types - `resource`, `resource_group` 
           - Users with the `provider` role can get tokens for all of the resources that belong to them without having to set any specific policies to access them.
            
          ## Tokens for delegates
          ### Delegation ID header
          - **The `delegationId` header must be included - the ID can be obtained by calling the GET /delegations API**
          - **The delegation ID determines which user + role + resource server the token request is being made on behalf by the delegate**  
        ---
          - Valid item types - `resource`, `resource_group` 
          - In case the delegate is making the request on behalf of a consumer, a token is issued if a successful APD verification takes place for the requested item and the associated consumer
          - In case the delegate is making the request on behalf of a provider,, a token is issued if the associated provider owns the item
          - On a successful token request, the access token will contain information about the delegator's user ID and role. See _JWT Access Token Response Structure_

          ## Tokens for consumers
          - Valid item types - `resource`, `resource_group`
          - Consumers are granted tokens if there is a successful APD verification for the requested item and associated consumer
          
          ## Tokens for admins
           **Admins are only permitted to get identity tokens.**
          
          ## JWT Access Token Response Structure
           The JWT is signed using the ES256 algorithm (`alg:ES256`).

           A valid IUDX AAA access token contains the following fields:
           - `sub` : `userId` of the user for whom the token is issued
           - `iss` : this tag contains the url of the server from the where the token was issued(IUDX auth server)
           - `aud` : the 'audience' tag contains the url of the server for which the token is valid
           - `exp` : when the token will expire in Unix format
           - `iat` : indicates when the token was issued in Unix format
           - `iid` : resource type and resource id of the item for which the token is valid
           - `role` : role of the user 
           - `cons` : the constraints that the resource server recognizes. Constraints sent back by the APD are included here. 
           - `rg` : when the requested item is a resource, this field exists containing the associated resource group ID
           - `did` : when role is `delegate`, contains the user ID of the delegator
           - `drl` : when the role is `delegate`, contains the role for which the delegated action is made
          
          # APD Verification 
         
        For all access token requests for a consumer, the AAA server queries the APD associated with the requested item  with relevant information to verify if the consumer has access to the item. The APD may respond in three ways:
        - **Allow** : The user has access. The AAA server generates the access token based on the constraints defined in the policy and sends it back.
            - In case the APD send constraints, these constraints will be put into the `apd` key in the JWT token in a JSON object called `apdConstraints`  

        - **Deny** : The user does not have access. The AAA server returns a `403 Forbidden`.
        - **Deny but the APD needs interaction** : The APD provides a mechanism for the user to interact with it. This interaction **may or may not** result in the user being given access. The AAA server sends a `403 Forbidden` but includes a special **APD JWT token** that the user must use when interacting with the APD. 

        ## Context object for extra information
        An APD may require extra information during evaluation. Any such information can be included in the `context` JSON object field in the API request body. 

        In case an APD requires particular keys in the `context` object, The APD can send a **Deny** response with the details of the required keys and information.

        ## JWT APD Token Response Structure
          The JWT is signed using the ES256 algorithm (`alg:ES256`).

         A valid IUDX AAA APD token contains the following fields:
         - `sub` : `userId` of the user for whom the token is issued
         - `iss` : this tag contains the url of the server from the where the token was issued(IUDX auth server)
         - `aud` : the 'audience' tag contains the url of the server for which the token is valid - in this case, will be the APD URL
         - `exp` : when the token will expire in Unix format
         - `iat` : indicates when the token was issued in unix format
         - `sid` : a session ID sent by the APD
         - `link` : a link to which the user can interact with the APD 
           
      tags:
        - Token APIs
      security:
        - authorization: []
  /auth/v1/introspect:
    post:
      summary: Introspect Token
      operationId: post-auth-v1-introspect
      responses:
        '200':
          description: Token validated.
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    type: 'urn:dx:as:Success'
                    title: Token authenticated
                    results:
                      sub: 129b4b55-0251-490e-bee9-00f3a5d3e632
                      iss: auth.test.com
                      aud: foobar.iudx.io
                      exp: 1626837909
                      iat: 1626794709
                      iid: 'rg:ae7f7313-61d9-46ab-9c33-7adc457ff0ed'
                      role: consumer
                      cons: {}
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: object
                    required:
                      - sub
                      - iss
                      - aud
                      - exp
                      - iat
                      - iid
                      - role
                      - cons
                    properties:
                      sub:
                        type: string
                        minLength: 1
                      iss:
                        type: string
                        minLength: 1
                      aud:
                        type: string
                        minLength: 1
                      exp:
                        type: number
                      iat:
                        type: number
                      iid:
                        type: string
                        minLength: 1
                      role:
                        type: string
                        minLength: 1
                      cons:
                        type: object
                required:
                  - type
                  - title
                  - results
              examples:
                Introspected Token:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Token authenticated
                    results:
                      sub: a6a23ee3-19fe-4a09-a78f-eb66dcb6b892
                      iss: authorization.iudx.org.in
                      aud: rs.iudx.org.in
                      exp: 1634233203
                      iat: 1634190003
                      iid: 'rg:a007f760-8580-4401-81c1-b123da3de06f'
                      role: consumer
                      cons:
                        access:
                          - api
                Introspecting an identity token:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Token authenticated
                    results:
                      sub: 72a08b8b-518f-4bff-b263-0693bc7f2e98
                      iss: authorization.iudx.org.in
                      aud: rs.iudx.org.in
                      exp: 1679935348
                      iat: 1679892148
                      iid: 'rs:rs.iudx.org.in'
                      role: consumer
                      cons: {}
                      userInfo:
                        email: user@datakaveri.org
                        name:
                          firstName: User
                          lastName: DataKaveri
        '400':
          description: |-
            - Missing/malformed token
            - The token has not been issued by the IUDX AAA server
            - The token is expired
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: array
                    uniqueItems: true
                    minItems: 1
                    items:
                      required:
                        - status
                      properties:
                        status:
                          type: string
                          minLength: 1
                required:
                  - type
                  - title
                  - results
                x-examples:
                  example-1:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    results:
                      - status: deny
              examples:
                Invalid/missing information:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    results:
                      - status: deny
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                accessToken:
                  type: string
                  minLength: 1
                  maxLength: 1000
                  example: JWT
              required:
                - accessToken
            examples:
              Introspect Token:
                value:
                  accessToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJzdWIiOiJhM2U3ZTM0Yy00NGJmLTQxZmYtYWQ4Ni0yZWUwNGE5NTQ0MTgiLCJpc3MiOiJhdXRoLnRlc3QuY29tIiwiYXVkIjoiZm9vYmFyLml1ZHguaW8iLCJleHAiOjE2MjY0NzMwNDgsImlhdCI6MTYyNjQyOTg0OCwiaWlkIjoicmc6ZXhhbXBsZS5jb20vOGQ0YjIwZWM0YmYyMWVmYjM2M2U3MjY3MWUxYjViZDc3ZmQ2Y2Y5MS9yZXNvdXJjZS1ncm91cCIsInJvbGUiOiJhZG1pbiIsImNvbnMiOnt9fQ.iyQXw21_4cXixVHm45rlHpzYjDz2PfTDRORbdQz9EHlLP_mQ-oBHZaWg1IWcuuoPS4FTRgNXWwM_uLhyxTDcuw
        description: '`accessToken` must be a valid JWT token'
        required: true
      description: |-
        Introspect a JWT token obtained from the AAA server. The API:
        - validates the token structure
        - checks if the token has been issued by the IUDX AAA server
        - checks if the token is expired
        If all checks pass, the decoded token is returned

        If an identity token is introspected, the user information of the user ID represented in the `sub` field is also included in the introspection response.
      tags:
        - Token APIs
    parameters: []
  /auth/v1/token/revoke:
    post:
      summary: Revoke Tokens
      operationId: post-auth-v1-revoke
      responses:
        '200':
          description: Successful token revocation
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: array
                    items: {}
                required:
                  - type
                  - title
              examples:
                Token revoked:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Token revoked
                    results: []
        '400':
          description: Invalid/missing information.
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  detail:
                    type: string
                    minLength: 1
                required:
                  - type
                  - title
                  - detail
              examples:
                Bad request:
                  value:
                    type: string
                    title: string
                    detail: string
        '401':
          description: '- Unauthorized - `token` invalid/expired'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Unauthorized:
                  value:
                    type: string
                    title: string
                    detail: string
      description: 'Revoke tokens **issued for a particular resource server or APD**. Once revoked, any tokens issued before the revocation with the `aud` field being the resource server should not be accepted by said resource server or APD.'
      tags:
        - Token APIs
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                rsUrl:
                  type: string
                  minLength: 1
                  pattern: '^[a-zA-Z0-9_\-\.]+$'
                  maxLength: 100
                  description: The resource server / APD URL
              required:
                - rsUrl
            examples:
              Revoke Request:
                value:
                  rsUrl: rs.iudx.org.in
        required: true
        description: '`rsUrl` is the URL/domain of a server that is recognised by the IUDX AAA '
      security:
        - authorization: []
    parameters: []
  /auth/v1/user/roles:
    post:
      summary: Add roles
      operationId: post-auth-v1-user-roles
      responses:
        '200':
          description: The roles have been added.
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: object
                    required:
                      - name
                      - roles
                      - rolesToRsMapping  
                      - userId
                      - email
                    properties:
                      name:
                        type: object
                        required:
                          - firstName
                          - lastName
                        properties:
                          firstName:
                            type: string
                            minLength: 1
                          lastName:
                            type: string
                            minLength: 1
                      roles:
                        type: array
                        items:
                          type: string
                      rolesToRsMapping:
                        type: object
                      userId:
                        type: string
                        minLength: 1
                      clients:
                        type: array
                        uniqueItems: true
                        minItems: 1
                        items:
                          type: object
                          properties:
                            clientName:
                              type: string
                              minLength: 1
                            clientId:
                              type: string
                              minLength: 1
                          required:
                            - clientName
                            - clientId
                      email:
                        type: string
                        minLength: 1
                      phone:
                        type: string
                        minLength: 1
                required:
                  - type
                  - title
                  - results
              examples:
                Add Roles Response:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Requested roles have been added
                    results:
                      name:
                        firstName: Foo
                        lastName: Bar
                      roles:
                        - consumer
                      rolesToRsMapping:
                        consumer:
                          - rs.cop.in
                      userId: 67194fc9-495e-40f7-b016-4470c1d4397f
                      clients:
                        - clientName: default
                          clientId: 6d0b58c3-c0c4-48af-bca2-4f255c0e73a7
                      email: ngoaf@chspomvjuq.com
                      phone: '9919967211'
        '400':
          description: |-
            - Malformed or missing data
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IUDX-AAA-Server_Error-Response'
              examples:
                Invalid roles array:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Missing or malformed parameters
                    detail: Invalid 'roles' array
                Resource Server does not exist:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Resource Server does not exist
                    detail: Resource Server does not exist
        '401':
          description: '- Unauthorized - `token` invalid/expired'
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
        '409':
          description: A requested role + resource server already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                User Already Exists:
                  value:
                    type: 'urn:dx:as:AlreadyExists'
                    title: Role for resource server already exists
                    detail: Provider/Consumer role exists for the requested resource servers
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      description: |-
        Add roles tied to a particular resource server in the COS. Current valid roles are:
        - **consumer**, which allows users to access to secure resources on the associated resource server
        - **provider**, which allows users to manage their resources on the particular resource server
          
        ## Provider registration
        **Once a provider role has been added for a resource server, the role request is subject to approval by the associated resource server admin**. The role for that resource server will be considered _pending_ till approved.

        ## Automatic Consumer role assignment for newly-added Resource Servers
        Any user who has the consumer role for any existing resource server **will automatically be assigned the consumer role for any newly added resource servers.**
      requestBody:
        content:
          application/json:
            schema:
              type: object
              anyOf:
                - required: [consumer]
                - required: [provider]
              additionalProperties: false
              properties:
                consumer:
                  type: array
                  description: List of resource servers for consumer role **in lowercase** 
                  minItems: 1
                  uniqueItems: true
                  items:
                    type: string
                    minLength: 1
                    pattern: '^[a-z0-9_\-\.]+$'
                    maxLength: 100
                provider:
                  type: array
                  description: List of resource servers for provider role **in lowercase**
                  minItems: 1
                  uniqueItems: true
                  items:
                    type: string
                    minLength: 1
                    pattern: '^[a-z0-9_\-\.]+$'
                    maxLength: 100
                phone:
                  type: string
                  description: Phone number  
                  example: '9900990099'
                  pattern: '^[9876]\d{9}$'
                  minLength: 10
                  maxLength: 10
                userInfo:
                  type: object
                  description: Any additional user information
                  minProperties: 0
                  maxProperties: 5
            examples:
              Add roles:
                value:
                  consumer:
                    - rs.cop.in
                  provider:
                    - rs.cop.in
                    - rs-one.cop.in
              Add roles and give phone and user info:
                value:
                  consumer:
                    - rs.cop.in
                  provider:
                    - rs.cop.in
                    - rs-one.cop.in
                  phone: 9889889881
                  userInfo:
                    organization: ACME Org.
                    natureOfOrg: Company   
                      
        description: |-
          - Users can add the `provider` or `consumer` role along with a list of resource servers to be associated with said role  
          - Resource server URLs in `provider` and `consumer` arrays must be **lowercase**  
          - `userInfo` is an optional field that can be populated with data required for user information, if desired
        required: true
      tags:
        - User APIs
      security:
        - authorization: []
    get:
      summary: List User Roles
      operationId: get-auth-v1-user-roles
      responses:
        '200':
          description: Successfully list user information and their approved roles
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: object
                    required:
                      - name
                      - userId
                      - email
                    properties:
                      name:
                        type: object
                        required:
                          - firstName
                          - lastName
                        properties:
                          firstName:
                            type: string
                            minLength: 1
                          lastName:
                            type: string
                            minLength: 1
                      roles:
                        type: array
                        items:
                          type: string
                      rolesToRsMapping:
                        type: object
                      userId:
                        type: string
                        minLength: 1
                      email:
                        type: string
                        minLength: 1
                      clients:
                        type: array
                        uniqueItems: true
                        minItems: 1
                        items:
                          type: object
                          properties:
                            clientName:
                              type: string
                              minLength: 1
                            clientId:
                              type: string
                              minLength: 1
                          required:
                            - clientName
                            - clientId
                      phone:
                        type: string
                        minLength: 1
                      organization:
                        type: object
                        properties:
                          name:
                            type: string
                            minLength: 1
                          url:
                            type: string
                            minLength: 1
                        required:
                          - name
                          - url
                required:
                  - type
                  - title
                  - results
              examples:
                Get User Roles:
                  value:
                    type: 'urn:dx:as:Success'
                    title: User details
                    results:
                      name:
                        firstName: B
                        lastName: c
                      roles:
                        - provider
                        - consumer
                      rolesToRsMapping:
                        provider:
                          - rs.cop.in
                        consumer:
                          - rs.cop.in
                      userId: a13eb955-c691-4fd3-b200-f18bc78810b5
                      email: bye@example.com
                      clients:
                        - clientName: default
                          clientId: a3e7e34c-44bf-41ff-ad86-2ee04a954418
                      phone: '9984567899'
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
        '401':
          description: |-
            - Unauthorized - `token` invalid/expired
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
        '404':
          description: |-
            - A user does not have any approved roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                User does not have any roles:
                  value:
                    type: 'urn:dx:as:MissingInformation'
                    title: User does not have any roles
                    detail: Please add roles or wait for provider role approvals
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      description: |-
        List roles of a user.

        The response contains user details such as **approved** roles, name, email. It also lists the client ID of the user in case the user has fetched their default client.
      tags:
        - User APIs
      security:
        - authorization: []
  /auth/v1/user/search:
    get:
      summary: Search for User - Trustee
      operationId: get-auth-v1-user-search
      responses:
        '200':
          description: Found user.
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: object
                    required:
                      - name
                      - userId
                      - email
                    properties:
                      name:
                        type: object
                        required:
                          - firstName
                          - lastName
                        properties:
                          firstName:
                            type: string
                            minLength: 1
                          lastName:
                            type: string
                            minLength: 1
                      userId:
                        type: string
                        minLength: 1
                      email:
                        type: string
                        minLength: 1
                required:
                  - type
                  - title
                  - results
              examples:
                Found user:
                  value:
                    type: 'urn:dx:as:Success'
                    title: User found
                    results:
                      email: someone@example.com
                      userId: a13eb955-c691-4fd3-b200-f18bc78810b5
                      name:
                        firstName: Someone
                        lastName: Person
        '400':
          description: |-
            - Malformed or missing data
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IUDX-AAA-Server_Error-Response'
              examples:
                Invalid email:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Missing or malformed parameters
                    detail: Invalid
        '404':
          description: |-
            - Requested user with email/user ID + role + resource server not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                User to be searched for cannot be found:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: User not found
                    detail: A user with given email, role and resource server not found
        '401':
          description: |-
            - Unauthorized - `clientId` & `clientSecret` invalid/not match
            - User does not have trustee role (i.e. is owner of registered and active APD)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Missing Authentication Details:
                  value:
                    type: 'urn:dx:as:MissingAuthenticationToken'
                    title: Missing auth details
                    detail: Missing auth details
      parameters:
        - schema:
            type: string
            format: uuid
            minLength: 36
            maxLength: 36
            pattern: '^[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12}$'
          in: header
          name: clientId
          description: AAA Client ID
          required: true  
        - schema:
            type: string
            maxLength: 40
            pattern: '^[0-9a-f]{40}$'
            minLength: 40
            example: 73b66ab55ba4d07ea487310679aa0689b4bd2c9d
          in: header
          description: AAA Client Secret
          name: clientSecret
          required: true  
        - schema:
            type: string
            pattern: '^(?=.{1,254}$)(?=.{1,64}@)[-!#$%&''*+/0-9=?A-Z^_`a-z{|}~]+(\.[-!#$%&''*+/0-9=?A-Z^_`a-z{|}~]+)*@[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$'
            format: email
          in: query
          name: email
        - schema:
            type: string
            format: uuid
          in: query
          name: userId
        - schema:
            type: string
            enum:
              - provider
              - consumer
          in: query
          name: role
          required: true
        - schema:
            type: string
            minLength: 1
            pattern: '^[a-zA-Z0-9_\-\.]+$'
            maxLength: 100
          in: query
          name: resourceServer
          required: true
      description: |-
        A valid user with **trustee** role i.e. **owner of a registered and active APD** may search for a user registered on the COS with provider/consumer roles by providing the email address **OR** COS user ID, role and resource server for which the role is applicable. If a user exists, then the user ID `userId`, email and name is returned. **The trustee is authenticated using client ID, client secret credentials.**
      tags:
        - User APIs
  /auth/v1/user/clientcredentials:
    get:
      summary: Create Default Client Credentials
      operationId: get-auth-v1-user-clientcredentials
      responses:
        '201':
          description: Created default client credentials. Once created, client secret cannot be recovered.
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: object
                    properties:
                      clientName:
                        type: string
                        minLength: 1
                      clientId:
                        type: string
                        minLength: 1
                      clientSecret:
                        type: string
                        minLength: 40
                        maxLength: 40
                        pattern: '^[0-9a-f]{40}$'
                    required:
                      - clientName
                      - clientId
                      - clientSecret
                required:
                  - type
                  - title
                  - results
              examples:
                Default client credentials created:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Created default client credentials
                    results:
                      clientName: default
                      clientId: 6d0b58c3-c0c4-48af-bca2-4f255c0e73a7
                      clientSecret: 73b66ab55ba4d07ea487310679aa0689b4bd2c9d
        '401':
          description: '- Unauthorized - `token` invalid/expired'
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
        '409':
          description: If default client credentials previously obtained 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Default client credentials previously obtained:
                  value:
                    type: 'urn:dx:as:AlreadyExists'
                    title: Default client credentials exists
                    detail: The default client credentials have already been created. If you have forgotten your client secret, please use the regenerate client secret API
                    context: 
                      clientId: 626b5314-7df4-404c-97bb-e07b49de0fb4 
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
        '404':
          description: |-
            - A user does not have any approved roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                User does not have any roles:
                  value:
                    type: 'urn:dx:as:MissingInformation'
                    title: User does not have any roles
                    detail: Please add roles or wait for provider role approvals
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      description: |-
        The user would receive a default client ID and a client secret. The client ID and client secret can be used instead of the OIDC flow to request for tokens. **The client secret is ONLY shown to the user here and can never be obtained again.**
      tags:
        - User APIs
      security:
        - authorization: []
    put:
      summary: 'Regenerate client secret'
      operationId: put-auth-v1-user-clientcredentials
      responses:
        '200':
          description: Successfully regenerated client secret
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: object
                    required:
                      - name
                      - roles
                      - rolesToRsMapping  
                      - userId
                      - clients
                      - email
                    properties:
                      keycloakId:
                        type: string
                        minLength: 1
                      name:
                        type: object
                        required:
                          - firstName
                          - lastName
                        properties:
                          firstName:
                            type: string
                            minLength: 1
                          lastName:
                            type: string
                            minLength: 1
                      roles:
                        type: array
                        items:
                          type: string
                      rolesToRsMapping:
                        type: object
                      userId:
                        type: string
                        minLength: 1
                      clients:
                        type: array
                        uniqueItems: true
                        minItems: 1
                        items:
                          type: object
                          properties:
                            clientName:
                              type: string
                              minLength: 1
                            clientId:
                              type: string
                              minLength: 1
                            clientSecret:
                              type: string
                          required:
                            - clientName
                            - clientId
                      email:
                        type: string
                        minLength: 1
                      phone:
                        type: string
                        minLength: 1
                required:
                  - type
                  - title
                  - results
              examples:
                Regenerated client secret successfully:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Regenerated client secret for requested client ID
                    results:
                      name:
                        firstName: Foo
                        lastName: Bar
                      roles:
                        - consumer
                      rolesToRsMapping:

                      userId: 67194fc9-495e-40f7-b016-4470c1d4397f
                      clients:
                        - clientName: default
                          clientId: 25b2c2d5-a7fc-47d0-89e4-8709a1560bfa
                          clientSecret: cf2f0e52df08ec08d7eb1706f7c63696a41de41e
                      email: ngoaf@chspomvjuq.com
                      phone: '9989967899'
        '400':
          description: |-
            - Missing or malformed data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad input:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Missing or malformed parameters
                    detail: Invalid 'roles' array
        '401':
          description: '- Unauthorized - `token` invalid/expired'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
        '404':
          description: |-
            - The client ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Client ID does not exist:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Invalid client ID
                    detail: Requested client ID not found
      description: |-
        A user may regenerate a client secret corresponding to a client ID in case they have lost the client secret or it has been compromised. A new client secret will be generated and sent as part of the output **and will not be shown again.** 

        ## Token revocation before regeneration
        In addition to regenerating the client secret, **the AAA server notifies all servers - resource servers and APDs - recognized by IUDX to revoke all tokens issued in the user's name (with the user's credentials) before the regeneration request was made**. The AAA server is effectively calling the `POST /auth/v1/token/revoke` API for all servers on behalf of the user. This is done to account for the scenario where the client secret has been compromised and tokens have been issued by a malicious user. 
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              additionalProperties: false
              properties:
                clientId:
                  type: string
                  pattern: '^[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12}$'
                  minLength: 36
                  maxLength: 36
                  format: uuid
                  description: A valid client ID belonging to the user
              required:
                - clientId
              type: object
            examples:
              Regenerate client secret:
                value:
                  clientId: 25b2c2d5-a7fc-47d0-89e4-8709a1560bfa
        description: |-
          - `clientId` is a valid client ID (belonging to the user) whose corresponding client secret needs to be generate
        required: true
      tags:
        - User APIs
      security:
        - authorization: []
  /auth/v1/resourceservers:
    get:
      summary: Get Registered Resource Servers
      tags:
        - Resource Server APIs
      responses:
        '200':
          description: Successfully retrieving the registered Resource Server details
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        url:
                          type: string
                        createdAt:
                          type: string
                        owner:
                          type: object
                          required:
                            - email
                            - name
                            - id
                          properties:
                            email:
                              type: string
                              minLength: 1
                            name:
                              type: object
                              required:
                                - firstName
                                - lastName
                              properties:
                                firstName:
                                  type: string
                                  minLength: 1
                                lastName:
                                  type: string
                                  minLength: 1
                            id:
                              type: string
                              minLength: 1
                required:
                  - type
                  - title
                  - results
              examples:
                Get Resource Server Details:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Resource Servers
                    results:
                      - id: bc51dfff-ee8b-4438-8c0c-5881a482e124
                        name: COP Resource Server
                        url: rs.cop.in
                        createdAt: 2023-06-21T13:17:10.433408  
                        owner:
                          email: rs-admin@datakaveri.org
                          name:
                            firstName: RS
                            lastName: Admin
                          id: 844e251b-574b-46e6-9247-f76f1f70a637
        '401':
          description: '- Unauthorized - `token` invalid/expired'
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
      operationId: get-auth-v1-resourceservers
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      description: Listing the details of registered resource servers
      security:
        - authorization: []
  /auth/v1/admin/resourceservers:
    post:
      summary: Create Resource Server - COS Admin
      operationId: post-auth-v1-admin-resourceservers
      responses:
        '201':
          description: A resource server has been created successfully.
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: object
                    properties:
                      id:
                        type: string
                        minLength: 1
                      name:
                        type: string
                        minLength: 1
                      url:
                        type: string
                      owner:
                        type: object
                        required:
                          - email
                          - name
                          - id
                        properties:
                          email:
                            type: string
                            minLength: 1
                          name:
                            type: object
                            required:
                              - firstName
                              - lastName
                            properties:
                              firstName:
                                type: string
                                minLength: 1
                              lastName:
                                type: string
                                minLength: 1
                          id:
                            type: string
                            minLength: 1
                    required:
                      - id
                      - name
                      - url
                      - owner  
                required:
                  - type
                  - title
                  - results
              examples:
                Created Resource Server:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Resource Server has been created
                    results:
                      id: bc51dfff-ee8b-4438-8c0c-5881a482e124
                      name: COP Resource Server
                      url: rs.cop.in
                      owner:
                        email: rs-admin@datakaveri.org
                        name:
                          firstName: RS
                          lastName: Admin
                        id: 844e251b-574b-46e6-9247-f76f1f70a637
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
        '400':
          description: |-
            - Malformed or missing data
            - Invalid `url`
            - Owner email not registered on UAC
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Invalid url:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Invalid URL
                    detail: The domain is invalid
                Emails not on UAC:
                  value:
                    type: urn:dx:as:InvalidInput
                    title: Email IDs not found at UAC
                    detail: Some email IDs have not been registered at UAC
                    context:
                      notFoundEmails:
                        - vtgusrficq@gmail.com
        '401':
          description: |-
            - Unauthorized - `token` invalid/expired
            - User is not the COS Admin
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
                User is not COS Admin:
                  value:
                    type: 'urn:dx:as:InvalidRole'
                    title: Not COS Admin
                    detail: You are not the COS Admin
        '409':
          description: If a resource server  with the requested `url` already exists
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAlreadyExists'
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:AlreadyExists'
                    title: Domains exists
                    detail: A resource server exists with the given domain
        '404':
          description: |-
            - A user does not have any approved roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                User does not have any roles:
                  value:
                    type: 'urn:dx:as:MissingInformation'
                    title: User does not have any roles
                    detail: Please add roles or wait for provider role approvals
      description: |-
        Register a Resource Server. This operation can be performed by the **COS Admin only**. 
        - The resource server is also assigned an owner/admin user during registration. The assigned admin/owner must be registered on the UAC.

        ## Automatic Consumer role assignment for new Resource Servers
        Any user who has the consumer role for any existing resource server **will automatically be assigned the consumer role for the newly added resource server.**
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  pattern: '^[a-zA-Z0-9]+(?:(?: |['' -])[a-zA-Z0-9]+)*$'
                  maxLength: 100
                  description: The name of the resource server  
                url:
                  type: string
                  minLength: 1
                  pattern: '^[a-zA-Z0-9_\-\.]+$'
                  maxLength: 100
                  description: The URL of the resource server  
                owner:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: The email of the admin of the resource server
                  pattern: '^(?=.{1,254}$)(?=.{1,64}@)[-!#$%&''*+/0-9=?A-Z^_`a-z{|}~]+(\.[-!#$%&''*+/0-9=?A-Z^_`a-z{|}~]+)*@[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$'
              required:
                - name
                - url
                - owner
            examples:
              Create Resource Server:
                value:
                  name: Data Kaveri
                  url: datakaveri.org
                  owner: datakaveri-admin@iudx.org.in  
        description: |-
          - The `owner`
        required: true
      tags:
        - Admin APIs
      security:
        - authorization: []
  /auth/v1/admin/provider/registrations:
    get:
      summary: Get Provider Registrations - RS Admin
      tags:
        - Admin APIs
      responses:
        '200':
          description: 'Successfully listing providers, their details with status.'
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: array
                    uniqueItems: true
                    minItems: 1
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          minLength: 1
                        userId:
                          type: string
                          minLength: 1
                        rsUrl:
                          type: string
                        status:
                          type: string
                          minLength: 1
                          enum:
                            - approved
                            - rejected
                            - pending
                        email:
                          type: string
                          minLength: 1
                        name:
                          type: object
                          properties:
                            firstName:
                              type: string
                              minLength: 1
                            lastName:
                              type: string
                              minLength: 1
                          required:
                            - firstName
                            - lastName
                        userInfo:
                          type: object
                      required:
                        - id
                        - userId
                        - status
                required:
                  - type
                  - title
                  - results
              examples:
                List of approved providers:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Provider registrations
                    results:
                      - id: c980f0c7-c5d4-4e30-9433-6ef405b98100
                        userId: 844e251b-574b-46e6-9247-f76f1f70a637
                        status: approved
                        rsUrl: rs.cop.in
                        email: xy@iisc.ac.in
                        name:
                          firstName: X
                          lastName: 'Y'
                        userInfo: {}
                      - id: 99023477-b3ba-408a-a3b5-e378615260ff
                        userId: a13eb955-c691-4fd3-b200-f18bc78810b5
                        status: approved
                        rsUrl: rs.cop.in
                        email: someone@example.com
                        name:
                          firstName: Someone
                          lastName: Person
                        userInfo: {}
                      - id: 0e36020a-edb1-4471-be21-a6c9946cdbb0
                        userId: d34b1547-7281-4f66-b550-ed79f9bb0c36
                        status: approved
                        rsUrl: rs.cop.in
                        email: individual@example.com
                        name:
                          firstName: Indiv
                          lastName: Vidual
                        userInfo: {}
                List of rejected providers:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Provider registrations
                    results:
                      - id: 5839621a-5a17-43c8-bdec-2eb1e0f95a3a
                        userId: e5bf3f6f-f22b-463d-aacb-cd62fbd8056f
                        status: rejected
                        rsUrl: rs.cop.in
                        userInfo: {}
                      - id: 07d28249-adb7-4257-bec7-bb5c154c6865
                        userId: fd0dfa08-d87a-4a51-86ce-060424f981c5
                        status: rejected
                        rsUrl: rs.cop.in
                        userInfo: {}
        '400':
          description: '- Invalid filter value'
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Invalid 'filter' value
                    detail: Invalid 'filter' value
        '401':
          description: |-
            - Unauthorized - `token` invalid/expired
            - User is not admin of any resource server
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
                Not admin of any resource server:
                  value:
                    type: 'urn:dx:as:InvalidRole'
                    title: Not admin of a resource server
                    detail: You are not an admin of any resource server
      operationId: get-auth-v1-admin-provider-registrations
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
        - schema:
            type: string
            enum:
              - pending
              - approved
              - rejected
            maxLength: 8
            minLength: 7
            default: pending
          in: query
          name: filter
          description: Filter the status of the Registration
      description: |-
        This operation can be performed by an admin of any registered resource server. Get all the provider registration details  for the resource servers owned by the user.
        The request can be filtered based on the status of registration using the query param `filter`.
        The various statuses are:
        - `pending`
        - `approved`
        - `rejected`

        If no `filter` value is given, registrations with status `pending` is returned.
      security:
        - authorization: []
    put:
      summary: Update Provider Registration status
      operationId: put-auth-v1-admin-provider-registrations
      responses:
        '200':
          description: Provider status successfully updated
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: array
                    uniqueItems: true
                    minItems: 1
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          minLength: 1
                        status:
                          type: string
                          minLength: 1
                          enum:
                            - approved
                            - rejected
                        userId:
                          type: string
                          minLength: 1
                        rsUrl:
                          type: string
                        email:
                          type: string
                          minLength: 1
                        name:
                          type: object
                          required:
                            - firstName
                            - lastName
                          properties:
                            firstName:
                              type: string
                              minLength: 1
                            lastName:
                              type: string
                              minLength: 1
                        userInfo:
                          type: object
                      required:
                        - id
                        - status
                        - userId
                        - rsUrl  
                        - email
                        - name
                        - userInfo  
                required:
                  - type
                  - title
                  - results
              examples:
                Provider Status Update:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Provider status updated
                    results:
                      - id: 0e36020a-edb1-4471-be21-a6c9946cdbb0
                        status: approved
                        userId: 355e251b-574b-46e6-9247-f76f1f70a123
                        rsUrl: rs.cop.in  
                        email: test@gmail.com
                        name:
                          firstName: First
                          lastName: Last
                        userInfo: {}
        '400':
          description: |-
            - Missing or malformed request
            - Duplicate `id`s in request
            - Invalid `id` - does not exist or not in pending state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Provider registration ID not valid, does not exist / not in pending state:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: 'Invalid provider registration ID - does not exist or not in pending state'
                    detail: c34b1565-7281-4f66-b220-ed79f9bb0a31
        '401':
          description: |-
            - Unauthorized - `token` invalid/expired
            - User is not an admin 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
                Not admin of any resource server:
                  value:
                    type: 'urn:dx:as:InvalidRole'
                    title: Not admin of a resource server
                    detail: You are not an admin of any resource server
      description: |-
        Update the status of multiple Provider registrations to `approved` or `rejected`. This operation can be performed by an admin of any registered resource server.
        The API takes the provider registration ID - `id` field obtained from the `GET /auth/v1/admin/provider/registrations` API - and the status to update.
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: ''
              properties:
                request:
                  type: array
                  uniqueItems: true
                  minItems: 1
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        pattern: '^[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12}$'
                      status:
                        type: string
                        enum:
                          - approved
                          - rejected
                    required:
                      - id
                      - status
              required:
                - request
            examples:
              Updating Registration status:
                value:
                  request:
                    - id: c34b1565-7281-4f66-b220-ed79f9bb0a31
                      status: approved
        required: true
        description: The request is an object with key `request` having value as an array of objects containing the provider registration IDs - `id` - from `GET /auth/v1/admin/provider/registrations` and the `status` to be updated for said provider
      tags:
        - Admin APIs
      security:
        - authorization: []
  /auth/v1/delegations:
    get:
      summary: Get Delegations
      responses:
        '200':
          description: 'Successfully list delegations. If the user does not have any valid delegations, the `results` array is empty.'
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: array
                    uniqueItems: true
                    minItems: 0
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          minLength: 1
                        url:
                          type: string
                          minLength: 1
                        server:
                          type: string
                          minLength: 1
                        role:
                          type: string
                          minLength: 1  
                        createdAt:
                          type: string
                        owner:
                          type: object
                          properties:
                            email:
                              type: string
                              minLength: 1
                            name:
                              type: object
                              required:
                                - firstName
                                - lastName
                              properties:
                                firstName:
                                  type: string
                                  minLength: 1
                                lastName:
                                  type: string
                                  minLength: 1
                            id:
                              type: string
                              minLength: 1
                          required:
                            - email
                            - name
                            - id
                        user:
                          type: object
                          properties:
                            email:
                              type: string
                              minLength: 1
                            name:
                              type: object
                              required:
                                - firstName
                                - lastName
                              properties:
                                firstName:
                                  type: string
                                  minLength: 1
                                lastName:
                                  type: string
                                  minLength: 1
                            id:
                              type: string
                              minLength: 1
                          required:
                            - email
                            - name
                            - id
                      required:
                        - id
                        - url
                        - server
                required:
                  - type
                  - title
                  - results
              examples:
                Success:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Delegations
                    results:
                      - id: 0bb3cd2b-331a-474c-8107-becdcbdb0b41
                        url: foobar.iudx.io
                        role: consumer  
                        server: Foobar
                        createdAt: 2023-06-21T13:17:10.433408  
                        owner:
                          email: someone@example.com
                          name:
                            firstName: Someone
                            lastName: Person
                          id: a13eb955-c691-4fd3-b200-f18bc78810b5
                        user:
                          email: individual@example.com
                          name:
                            firstName: Indiv
                            lastName: Vidual
                          id: d34b1547-7281-4f66-b550-ed79f9bb0c36
                      - id: 8f79dec9-a327-439c-b00b-731fea264af4
                        url: foobar.iudx.io
                        role: provider  
                        server: Foobar
                        owner:
                          email: bob_provider@iisc.ac.in
                          name:
                            firstName: Bob
                            lastName: Provider
                          id: 844e251b-574b-46e6-9247-f76f1f70a637
                        user:
                          email: someone@example.com
                          name:
                            firstName: Someone
                            lastName: Person
                          id: a13eb955-c691-4fd3-b200-f18bc78810b5
                User does not have any valid delegations:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Delegations
                    results: []
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
        '401':
          description: |-
            - Unauthorized - `token` invalid/expired
            - User does have the `provider`, `consumer` or `delegate` roles
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Invalid.expired token:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
                User does not have required roles:
                  value:
                    type: 'urn:dx:as:InvalidRole'
                    title: User does not have roles to use API
                    detail: User with provider/consumer role or delegate role may call the API
      operationId: get-auth-v1-delegations
      description: |-
        Get delegations related to a particular user. The response depends upon the roles that the user has:
        - `provider`/`consumer` : returns all delegations created by the provider/consumer
        - `delegate` : returns all providers/consumers who have assigned them as delegates for certain resource servers

      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      security:
        - authorization: []
      tags:
        - Delegation APIs
    parameters: []
    delete:
      summary: Delete Delegations
      operationId: delete-auth-v1-delegations
      responses:
        '200':
          description: Successfully deleted the requested delegations
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: object
                required:
                  - type
                  - title
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Deleted requested delegations
                    results: {}
        '400':
          description: |-
            - Invalid or malformed request
            - An invalid/deleted delegation ID is sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Invalid/deleted delegation ID:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Invalid delegation ID
                    detail: 5dd1c776-8ba6-4272-b157-0a5de2035355
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
        '401':
          description: |-
            - Unauthorized - `token` invalid/expired
            - User does have the `provider` or `consumer` role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Invalid/Expired token:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
                User does not have valid roles:
                  value:
                    type: 'urn:dx:as:InvalidRole'
                    title: User does not have roles to use API
                    detail: User with provider or consumer role may call the API
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
      description: |
        A provider or consumer may delete delegations created by them. 
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: ''
              properties:
                request:
                  type: array
                  minItems: 1
                  uniqueItems: true
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        pattern: '^[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12}$'
                        minLength: 36
                        maxLength: 36
                        format: uuid
                    required:
                      - id
              required:
                - request
            examples:
              Example:
                value:
                  request:
                    - id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
        description: The body is a JSON object with a JSON array containing the delegation IDs. The IDs can be obtained from the `GET /auth/v1/delegations` API
        required: true
      security:
        - authorization: []
      tags:
        - Delegation APIs
    post:
      summary: Create Delegations
      operationId: post-auth-v1-delegations
      responses:
        '201':
          description: Created delegations
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: object
                required:
                  - type
                  - title
              examples:
                Created delegations:
                  value:
                    type: 'urn:dx:as:Success'
                    title: added delegations
        '400':
          description: |-
            - Bad Request
            - The resource server URL is not present on the server
            - The user does not have the correct role for the requested resource server  
            - The requested user email is not registered on the UAC 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                RS URL not present / User does have role for RS:
                  value:
                    type: urn:dx:as:InvalidInput
                    title: 'User does not have role for requested RS URL / RS does not exist'
                    detail: User does not have requested delegated role for given resource server (Resource server may not exist also)
                    context:
                      rsUrls:
                        - sbtuuosujr.com
                Emails not on UAC:
                  value:
                    type: urn:dx:as:InvalidInput
                    title: Email IDs not found at UAC
                    detail: Some email IDs have not been registered at UAC
                    context:
                      notFoundEmails:
                        - vtgusrficq@gmail.com
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
        '401':
          description: |-
            - Unauthorized - `token` invalid/expired
            - User does not have consumer/provider role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Does not have role:
                  value:
                    type: urn:dx:as:InvalidRole
                    title: User does not have roles to use API
                    detail: User with provider/consumer role may call the API  
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
        '409':
          description: |-
            - Delegation already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'  
              examples:
                Delegation already exists:
                  value:
                    type: urn:dx:as:AlreadyExists
                    title: Delegation already exists
                    detail: A delegation already exists for a requested user + role + resource server
                    context:
                      existingDelegationIds:
                        - dc31e990-3dec-40be-837c-dc8457e74853
      description: |
        Allow consumers and providers to create consumer-delegates or provider delegates respectively for a particular resource server. The delegates will be allowed to perform operations on behalf of the consumer or provider on the resource server or on entities belonging to the resource server.

        The user intended to be the delegate (`userEmail`)  must be registered on the UAC. They will be given the **delegate** role as a result of successful delegation creation.
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      security:
        - authorization: []
      tags:
        - Delegation APIs
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                request:
                  type: array
                  uniqueItems: true
                  minItems: 1
                  items:
                    type: object
                    properties:
                      resSerUrl:
                        type: string
                        minLength: 1
                        pattern: '^[a-z0-9_*\-*\.\/]+$'
                        maxLength: 100
                        description: URL of the resource server the user is to be made a delegate for **in lowercase**  
                      userEmail:
                        type: string
                        format: email
                        pattern: '^(?=.{1,254}$)(?=.{1,64}@)[-!#$%&''*+/0-9=?^_`a-z{|}~]+(\.[-!#$%&''*+/0-9=?^_`a-z{|}~]+)*@[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$'
                        description: Email address of the user to be made delegate **in lowercase** 
                      role:
                        type: string
                        description: Role for which the user can operate on the resource server 
                        enum:
                          - consumer
                          - provider
                    required:
                      - resSerUrl
                      - userEmail
                      - role  
              required:
                - request
            examples:
              Single Request:
                value:
                  request:
                    - resSerUrl: rs.iudx.io
                      userEmail: email@email.com
                      role: consumer
              Multiple Request:
                value:
                  request:
                    - resSerUrl: rs.iudx.io
                      userEmail: email@email.com
                      role: consumer
                    - resSerUrl: auth.iudx.io
                      userEmail: email@email.com
                      role: provider
        description: |-
          - `userEmail`, `resSerUrl` **must be in lowercase**
        required: true
  /auth/v1/delegations/emails:
    get:
      summary: Get Delegate Emails - Trustee
      responses:
        '200':
          description: 'Successfully get list of delegate emails. If the requested user does not exist or does not have any valid delegations for the given role and resource server, `delegateEmails` array will be empty'
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: object
                    properties:
                      delegateEmails:
                        type: array
                        minLength: 0
                        items:
                          type: string
                    required:
                      - delegateEmails
                required:
                  - type
                  - title
                  - results
              examples:
                Success:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Delegate emails
                    results:
                      delegateEmails:
                        - delegate-one@datakaveri.org
                        - delegate2@datakaveri.org
                Requested user not registered on COS / does not have any valid delegations for role + RS:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Delegate emails
                    results:
                      delegateEmails: []
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
        '401':
          description: |-
            - Unauthorized - `clientId` & `clientSecret` invalid/not match
            - User does not have trustee role (i.e. is owner of registered and active APD)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Missing Authentication Details:
                  value:
                    type: 'urn:dx:as:MissingAuthenticationToken'
                    title: Missing auth details
                    detail: Missing auth details
      operationId: get-auth-v1-delegations-emails
      description: |-
        A valid user with **trustee** role i.e. **owner of a registered and active APD** may get the email addresses of a user's delegates for communication purposes. The trustee supplies a user ID, role and resource server. If a user has valid delegates for the given role and resource server, the email addresses are returned. **The trustee is authenticated using client ID, client secret credentials.** 
        
        **NOTE**: A `200 OK` with an empty `delegateEmails` array is returned even if 
          - The requested user **is not registered on the COS** or **does not exist on UAC**
          - The requested **resource server does not exist**
          - The requested user **does not have a role for the requested resource server**

      parameters:
        - schema:
            type: string
            format: uuid
            pattern: '^[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12}$'
          in: header
          name: clientId
          description: AAA Client ID
          required: true  
        - schema:
            type: string
            maxLength: 40
            pattern: '^[0-9a-f]{40}$'
            minLength: 40
            example: 73b66ab55ba4d07ea487310679aa0689b4bd2c9d
          in: header
          description: AAA Client Secret
          name: clientSecret
          required: true  
        - schema:
            type: string
            format: uuid
          in: query
          name: userId
          description: User ID of delegator / user who made delegations
          required: true
        - schema:
            type: string
            enum:
              - provider
              - consumer
          in: query
          name: role
          description: The delegated role
          required: true
        - schema:
            type: string
            minLength: 1
            pattern: '^[a-zA-Z0-9_\-\.]+$'
            maxLength: 100
          in: query
          description: The delegated resource server URL
          name: resourceServer
          required: true
      tags:
        - Delegation APIs
    parameters: []
  /auth/v1/cert:
    get:
      summary: Get JWT Certificate
      tags:
        - Certificate API
      responses:
        '200':
          description: Successfully list the Certificate
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  cert:
                    type: string
                    minLength: 1
                required:
                  - cert
                x-examples:
                  example-1:
                    cert: |-
                      -----BEGIN CERTIFICATE-----
                      MIIBnzCCAUOgAwIBAgIIBXqRSbCK9qUwDAYIKoZIzj0EAwIFADBCMQkwBwYDVQQGEwAxCTAHBgNVBAgTADEJMAcGA1UEBxMAMQkwBwYDVQQKEwAxCTAHBgNVBAsTADEJMAcGA1UEAxMAMB4XDTIxMDYwNTE1MDEyOFoXDTIyMDUzMTE1MDEyOFowQjEJMAcGA1UEBhMAMQkwBwYDVQQIEwAxCTAHBgNVBAcTADEJMAcGA1UEChMAMQkwBwYDVQQLEwAxCTAHBgNVBAMTADBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPASn9h2d8LesDX99EiLG8o2D5JE0hhssjNvzBhf82E2VfWdvIR8L2YEn527Kxd+gQSp1rM5TmFtAInsgFCminajITAfMB0GA1UdDgQWBBQUKmbmWE9Kv1PzPjRj5RMoTCErkDAMBggqhkjOPQQDAgUAA0gAMEUCIGysQH9MjOCbTYZQbiwaWGCP3yTFwz4jyRLJYZslloesAiEAvfZaflCesKaeOYS+7htQg0mnnUOlkBRq+POfqoF77fM=
                      -----END CERTIFICATE-----
              examples:
                Certificate:
                  value:
                    cert: |-
                      -----BEGIN CERTIFICATE-----
                      MIIBnzCCAUOgAwIBAgIIBXqRSbCK9qUwDAYIKoZIzj0EAwIFADBCMQkwBwYDVQQGEwAxCTAHBgNVBAgTADEJMAcGA1UEBxMAMQkwBwYDVQQKEwAxCTAHBgNVBAsTADEJMAcGA1UEAxMAMB4XDTIxMDYwNTE1MDEyOFoXDTIyMDUzMTE1MDEyOFowQjEJMAcGA1UEBhMAMQkwBwYDVQQIEwAxCTAHBgNVBAcTADEJMAcGA1UEChMAMQkwBwYDVQQLEwAxCTAHBgNVBAMTADBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPASn9h2d8LesDX99EiLG8o2D5JE0hhssjNvzBhf82E2VfWdvIR8L2YEn527Kxd+gQSp1rM5TmFtAInsgFCminajITAfMB0GA1UdDgQWBBQUKmbmWE9Kv1PzPjRj5RMoTCErkDAMBggqhkjOPQQDAgUAA0gAMEUCIGysQH9MjOCbTYZQbiwaWGCP3yTFwz4jyRLJYZslloesAiEAvfZaflCesKaeOYS+7htQg0mnnUOlkBRq+POfqoF77fM=
                      -----END CERTIFICATE-----
      operationId: get-auth-v1-cert
      description: Get the JsonObject having certificate to authenticate/validate the generated JWT using `/auth/v1/token`
  /auth/v1/jwks:
      get:
        summary: Get public key in JWKS format.
        tags:
          - Certificate API
        responses:
          '200':
            description: Successfully generated the public key in JWKS format.
            headers:
              Content-Type:
                schema:
                  type: string
                description: application/json
            content:
              application/json:
                schema:
                  description: ''
                  type: object
                  properties:
                    keys:
                      type: array
                      uniqueItems: true
                      minItems: 1
                      items:
                        required:
                          - kty
                          - x5t#S256
                          - crv
                          - kid
                          - x5c
                          - x
                          - y
                        properties:
                          kty:
                            type: string
                            minLength: 1
                          x5t#S256:
                            type: array
                            minLength: 1
                          crv:
                            type: string
                            minLength: 1
                          kid:
                            type: string
                            minLength: 1
                          x5c:
                            type: string
                            minLength: 1
                          x:
                            type: string
                            minLength: 1
                          y:
                            type: string
                            minLength: 1
                  required:
                    - keys
                  x-examples:
                    example-1:
                    keys:
                      - kty: EC
                        x5t#S256: tCrGI3X7KS4WhHwGqR89Z6lWwPidOAb_CFYCzQpQN3M
                        crv: P-256
                        kid: ES256
                        x5c:
                          - MIIBnDCCAT+gAwIBAgIEEC1BXTAMBggqhkjOPQQDAgUAMEIxCTAHBgNVBAYTADEJMAcGA1UECBMAMQkwBwYDVQQHEwAxCTAHBgNVBAoTADEJMAcGA1UECxMAMQkwBwYDVQQDEwAwHhcNMjMwNjA1MDUwODQ4WhcNMjQwNjA0MDUwODQ4WjBCMQkwBwYDVQQGEwAxCTAHBgNVBAgTADEJMAcGA1UEBxMAMQkwBwYDVQQKEwAxCTAHBgNVBAsTADEJMAcGA1UEAxMAMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAErVwOLOln7NhUdfZOQFfTOtJ62AgdKUeYZm8DgWCWJHaaXT95dipr94zJM+inSuqohVFCTxjajdTH8/O9JO43rKMhMB8wHQYDVR0OBBYEFNH2u8eeqj3509HAFJQS4F5NF4TQMAwGCCqGSM49BAMCBQADSQAwRgIhAL7zHYdN6PFTccFm1y07X0t2mJxNfgOaxihTi2tA9D8AAiEAomGmBvXA72X1gfhK3dhaDSd52BN1fUP/ALYNiyuXHg0=
                        x: rVwOLOln7NhUdfZOQFfTOtJ62AgdKUeYZm8DgWCWJHY
                        y: ml0_eXYqa_eMyTPop0rqqIVRQk8Y2o3Ux_PzvSTuN6w

                examples:
                  Certificate:
                    value:
                      keys:
                        - kty: EC
                          x5t#S256: tCrGI3X7KS4WhHwGqR89Z6lWwPidOAb_CFYCzQpQN3M
                          crv: P-256
                          kid: ES256
                          x5c:
                            - MIIBnDCCAT+gAwIBAgIEEC1BXTAMBggqhkjOPQQDAgUAMEIxCTAHBgNVBAYTADEJMAcGA1UECBMAMQkwBwYDVQQHEwAxCTAHBgNVBAoTADEJMAcGA1UECxMAMQkwBwYDVQQDEwAwHhcNMjMwNjA1MDUwODQ4WhcNMjQwNjA0MDUwODQ4WjBCMQkwBwYDVQQGEwAxCTAHBgNVBAgTADEJMAcGA1UEBxMAMQkwBwYDVQQKEwAxCTAHBgNVBAsTADEJMAcGA1UEAxMAMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAErVwOLOln7NhUdfZOQFfTOtJ62AgdKUeYZm8DgWCWJHaaXT95dipr94zJM+inSuqohVFCTxjajdTH8/O9JO43rKMhMB8wHQYDVR0OBBYEFNH2u8eeqj3509HAFJQS4F5NF4TQMAwGCCqGSM49BAMCBQADSQAwRgIhAL7zHYdN6PFTccFm1y07X0t2mJxNfgOaxihTi2tA9D8AAiEAomGmBvXA72X1gfhK3dhaDSd52BN1fUP/ALYNiyuXHg0=
                          x: rVwOLOln7NhUdfZOQFfTOtJ62AgdKUeYZm8DgWCWJHY
                          y: ml0_eXYqa_eMyTPop0rqqIVRQk8Y2o3Ux_PzvSTuN6w

        operationId: get-auth-v1-jwks
        description: Get the public key in JWKS format to authenticate/validate the generated JWT using `/auth/v1/token`
  /auth/v1/apd:
    get:
      summary: Get registered Access Policy Domains
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: array
                    uniqueItems: true
                    minItems: 1
                    items:
                      required:
                        - id
                        - name
                        - url
                        - status
                      properties:
                        id:
                          type: string
                          minLength: 1
                        name:
                          type: string
                          minLength: 1
                        url:
                          type: string
                          minLength: 1
                        status:
                          type: string
                          minLength: 1
                        owner:
                          type: object
                          required:
                            - email
                            - name
                            - id
                          properties:
                            email:
                              type: string
                              minLength: 1
                            name:
                              type: object
                              required:
                                - firstName
                                - lastName
                              properties:
                                firstName:
                                  type: string
                                  minLength: 1
                                lastName:
                                  type: string
                                  minLength: 1
                            id:
                              type: string
                              minLength: 1
                required:
                  - type
                  - title
                  - results
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:Success'
                    title: Access Policy Domains
                    results:
                      - id: 5d019ee7-e1d4-4f65-9a14-2e3b656b7296
                        name: DataKaveri APD
                        url: apd.datakaveri.org
                        status: active
                        owner:
                          email: apd-admin@datakaveri.org
                          name:
                            firstName: APD
                            lastName: Admin
                          id: fffe251b-574b-46e6-9247-f76f1f70a637
                      - id: 540972fd-43df-43c1-9627-df2402a6b731
                        name: IISc APD
                        url: apd.iisc.ac.in
                        status: active
        '401':
          description: '- Unauthorized - `token` invalid/expired'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IUDX-AAA-Server_Error-Response'
              examples:
                Invalid token:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
        '404':
          description: |-
            - A user does not have any approved roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                User does not have any roles:
                  value:
                    type: 'urn:dx:as:MissingInformation'
                    title: User does not have any roles
                    detail: Please add roles or wait for provider role approvals
      operationId: get-auth-v1-apd
      description: |-
        Returns registered APDs. 
        - If called by the COS Admin, returns all APD registrations
        - If called by a user with any other roles, returns all APDs in the **active** state
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      security:
        - authorization: []
      tags:
        - Access Policy Domain (APD) APIs
    post:
      summary: Register an Access Policy Domain - COS Admin
      operationId: post-auth-v1-apd
      responses:
        '201':
          description: The APD has been successfully registered
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: object
                    properties:
                      id:
                        type: string
                        minLength: 1
                      name:
                        type: string
                        minLength: 1
                      owner:
                        type: object
                        required:
                          - email
                          - name
                          - id
                        properties:
                          email:
                            type: string
                            minLength: 1
                          name:
                            type: object
                            required:
                              - firstName
                              - lastName
                            properties:
                              firstName:
                                type: string
                                minLength: 1
                              lastName:
                                type: string
                                minLength: 1
                          id:
                            type: string
                            minLength: 1
                      url:
                        type: string
                        minLength: 1
                      status:
                        type: string
                        minLength: 1
                    required:
                      - id
                      - name
                      - url
                      - owner
                      - status
                required:
                  - type
                  - title
                  - results
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:Success'
                    title: The Access Policy Domain has been registered
                    results:
                      id: 5d019ee7-e1d4-4f65-9a14-2e3b656b7296
                      name: DataKaveri APD
                      url: apd.datakaveri.org
                      owner:
                        email: apd-admin@datakaveri.org
                        name:
                          firstName: APD
                          lastName: Admin
                        id: fffe251b-574b-46e6-9247-f76f1f70a637
                      status: active
        '400':
          description: |-
            - Malformed or missing data
            - Invalid `url`
            - Owner email not registered on UAC  
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IUDX-AAA-Server_Error-Response'
              examples:
                Invalid url:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Invalid URL
                    detail: The URL is invalid
                Emails not on UAC:
                  value:
                    type: urn:dx:as:InvalidInput
                    title: Email IDs not found at UAC
                    detail: Some email IDs have not been registered at UAC
                    context:
                      notFoundEmails:
                        - vtgusrficq@gmail.com
        '401':
          description: '- Unauthorized - `token` invalid/expired or not COS Admin'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              examples:
                Inactive/invalid token:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
                Not COS Admin:
                  value:
                    type: 'urn:dx:as:InvalidRole'
                    title: Not COS Admin
                    detail: User is not the COS Admin
        '409':
          description: '- An APD with the provided `url` already exists'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IUDX-AAA-Server_Error-Response'
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:AlreadyExists'
                    title: URL already exists
                    detail: An APD with the requested URL already exists
      description: |-
        The COS Admin can add new APDs to the server. These APDs will be in the **active** state by default. 
        - The resource server is also assigned an owner/trustee user during registration. The assigned owner/trustee must be registered on the UAC. They will be given the **trustee role** as a result of successful APD registration.

        **NOTE**: The trustee role assignment exists as long as the APD is in active state.

      security:
        - authorization: []
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  pattern: '^[a-zA-Z0-9]+(?:(?: |['' -])[a-zA-Z0-9]+)*$'
                  minLength: 1
                  maxLength: 100
                  description: The name of the APD
                url:
                  type: string
                  minLength: 1
                  pattern: '^[a-zA-Z0-9_\-\.]+$'
                  maxLength: 100
                  description: The APD URL
                owner:
                  type: string
                  minLength: 1
                  maxLength: 100
                  pattern: '^(?=.{1,254}$)(?=.{1,64}@)[-!#$%&''*+/0-9=?A-Z^_`a-z{|}~]+(\.[-!#$%&''*+/0-9=?A-Z^_`a-z{|}~]+)*@[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$'
                  description: The email of the APD owner  
              required:
                - name
                - url
                - owner  
            examples:
              Example:
                value:
                  name: DataKaveri APD
                  url: apd.datakaveri.org
                  owner: apd-admin@datakaveri.org  
        required: true
        description: |-
          - COS Admin permitted to call the API.
          - `url` must be a **valid reachable domain/hostname**. Examples of invalid `url`s are:
            - `https://example.com`
            - `example.com:8080`
            - `example.com/apd`
      tags:
        - Access Policy Domain (APD) APIs
    put:
      summary: Update Access Policy Domain status - COS Admin
      operationId: put-auth-v1-apd
      responses:
        '200':
          description: The statuses of the requested APDs have been updated successfully
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  type:
                    type: string
                    minLength: 1
                  title:
                    type: string
                    minLength: 1
                  results:
                    type: array
                    uniqueItems: true
                    minItems: 1
                    items:
                      required:
                        - id
                        - name
                        - url
                        - status
                      properties:
                        id:
                          type: string
                          minLength: 1
                        name:
                          type: string
                          minLength: 1
                        url:
                          type: string
                          minLength: 1
                        status:
                          type: string
                          minLength: 1
                          required:
                            - email
                            - name
                            - id
                required:
                  - type
                  - title
                  - results
                x-examples:
                  example-1:
                    type: 'urn:dx:as:Success'
                    title: The status of the Access Policy Domains have been updated
                    results:
                      - id: 11f0335d-0d0a-4f58-99b1-08e60e3f4750
                        name: zwcev
                        url: zwcev.com
                        status: inactive
              examples:
                Example:
                  value:
                    type: 'urn:dx:as:Success'
                    title: The status of the Access Policy Domains have been updated
                    results:
                      - id: 5d019ee7-e1d4-4f65-9a14-2e3b656b7296
                        name: DataKaveri APD
                        url: apd.datakaveri.org
                        status: active
                      - id: 540972fd-43df-43c1-9627-df2402a6b731
                        name: IISc APD
                        url: apd.iisc.ac.in
                        status: inactive
        '400':
          description: |-
            - Malformed or missing data
            - Invalid/non-existent APD ID
            - Duplicate APD IDs in `request` array
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IUDX-AAA-Server_Error-Response'
              examples:
                Invalid APD ID:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Invalid APD ID
                    detail: 00e3035b-c91d-487a-b67a-a7f7daa12723
                Duplicate APD IDs in request array:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Duplicate APD ID in request
                    detail: 22bf1df3-7704-4be3-b64a-7f1fb8d1e97d
        '401':
          description: '- Unauthorized - `token` invalid/expired or not COS admin'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IUDX-AAA-Server_Error-Response'
              examples:
                Invalid/expired token:
                  value:
                    type: 'urn:dx:as:InvalidAuthenticationToken'
                    title: Token authentication failed
                    detail: Inactive Token
                Not COS Admin:
                  value:
                    type: 'urn:dx:as:InvalidRole'
                    title: Not COS Admin
                    detail: User is not the COS Admin
        '403':
          description: |-
            - Cannot change status of a particular APD
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IUDX-AAA-Server_Error-Response'
              examples:
                Cannot change status of an APD:
                  value:
                    type: 'urn:dx:as:InvalidInput'
                    title: Not allowed to change status for APD ID
                    detail: 073a3628-1f21-4828-bdeb-9620dfd6ed42
        '404':
          description: |-
            - A user does not have any approved roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                User does not have any roles:
                  value:
                    type: 'urn:dx:as:MissingInformation'
                    title: User does not have any roles
                    detail: Please add roles or wait for provider role approvals
      description: |-
        Allows the COS Admin to update status of APDs.

        The COS Admin may change status :
        - from **active** to **inactive**, in case the APD is not responsive or has been compromised
        - from **inactive** to **active**
      parameters:
        - schema:
            type: string
            maxLength: 4000
            minLength: 1
            example: Bearer <JWT>
          in: header
          name: Authorization
          description: Keycloak Issued token
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: ''
              x-examples:
                example-1:
                  request:
                    - id: 3f08e1ba-f4c0-4ed0-86da-edf7092d6333
                      status: active
              additionalProperties: false
              properties:
                request:
                  type: array
                  uniqueItems: true
                  minItems: 1
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      id:
                        type: string
                        minLength: 36
                        format: uuid
                        pattern: '^[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12}$'
                        maxLength: 36
                        description: The APD ID
                      status:
                        type: string
                        minLength: 1
                        enum:
                          - active
                          - inactive
                        description: The status to be changed to
                    required:
                      - id
                      - status
              required:
                - request
            examples:
              Example:
                value:
                  request:
                    - id: 5d019ee7-e1d4-4f65-9a14-2e3b656b7296
                      status: active
                    - id: 540972fd-43df-43c1-9627-df2402a6b731
                      status: inactive
      security:
        - authorization: []
      tags:
        - Access Policy Domain (APD) APIs
components:
  schemas:
    RequestToken:
      description: Request payload for create token
      type: object
      properties:
        itemId:
          type: string
          minLength: 1
        itemType:
          type: string
          minLength: 1
        role:
          type: string
          minLength: 1
      required:
        - itemId
        - itemType
        - role
      title: RequestToken
      x-examples:
        example-1:
          itemId: string
          itemType: string
          role: string
    RevokeToken:
      description: ''
      type: object
      properties:
        clientId:
          type: string
          minLength: 1
        rsUrl:
          type: string
          minLength: 1
      required:
        - clientId
        - rsUrl
    ErrorResponse:
      description: ''
      type: object
      x-examples:
        Example:
          type: string
          title: string
          detail: string
      properties:
        type:
          type: string
          minLength: 1
        title:
          type: string
          minLength: 1
        detail:
          type: string
          minLength: 1
        context:
          type: object
          description: Any additional information required
      required:
        - type
        - title
        - detail
    UserAlreadyExists:
      description: ''
      type: object
      properties:
        type:
          type: string
          minLength: 1
        title:
          type: string
          minLength: 1
        detail:
          type: string
          minLength: 1
      required:
        - type
        - title
        - detail
      x-examples: {}
    Unauthorized:
      description: ''
      x-examples:
        example-1:
          value:
            type: 'urn:dx:as:MissingAuthenticationToken'
            title: Missing auth details
            detail: Missing auth details
      type: object
      properties:
        type:
          type: string
          minLength: 1
        title:
          type: string
          minLength: 1
        detail:
          type: string
          minLength: 1
      required:
        - type
        - title
        - detail
    IUDX-AAA-Server_Error-Response:
      title: Error-Response
      type: object
      x-examples: {}
      properties:
        type:
          type: string
          description: A URN
        title:
          type: string
        detail:
          type: string
      required:
        - type
        - title
        - detail
    AccessRequest:
      description: ''
      type: object
      x-examples:
        Example:
          type: 'urn:dx:as:Success'
          title: User permission requests
          results:
            - requestId: e4619679-f5d9-4eff-9f79-bbded6130bb1
              itemId: string
              itemType: resource_server
              status: pending
              expiryDuration: string
              constraints:
                access:
                  - api
                  - sub
                  - file
              user:
                id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                email: user@example.com
                name:
                  firstName: string
                  lastName: string
              owner:
                id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                email: user@example.com
                name:
                  firstName: string
                  lastName: string
      properties:
        type:
          type: string
          minLength: 1
        title:
          type: string
          minLength: 1
        results:
          type: array
          uniqueItems: true
          minItems: 1
          items:
            type: object
            properties:
              requestId:
                type: string
                minLength: 1
                format: uuid
              itemId:
                type: string
                minLength: 1
              itemType:
                type: string
                minLength: 1
              status:
                type: string
                minLength: 1
              expiryDuration:
                type: string
                minLength: 1
              constraints:
                type: object
              user:
                type: object
                properties:
                  id:
                    type: string
                    minLength: 1
                  email:
                    type: string
                    minLength: 1
                  name:
                    type: object
                    required:
                      - firstName
                      - lastName
                    properties:
                      firstName:
                        type: string
                        minLength: 1
                      lastName:
                        type: string
                        minLength: 1
                required:
                  - id
                  - email
                  - name
              owner:
                type: object
                properties:
                  id:
                    type: string
                    minLength: 1
                  email:
                    type: string
                    minLength: 1
                  name:
                    type: object
                    required:
                      - firstName
                      - lastName
                    properties:
                      firstName:
                        type: string
                        minLength: 1
                      lastName:
                        type: string
                        minLength: 1
                required:
                  - id
                  - email
                  - name
            required:
              - requestId
              - itemId
              - itemType
              - status
              - expiryDuration
      required:
        - type
        - title
        - results
    User:
      description: ''
      type: object
      properties:
        id:
          type: string
          minLength: 1
        email:
          type: string
          minLength: 1
        name:
          type: object
          properties:
            firstName:
              type: string
              minLength: 1
            lastName:
              type: string
              minLength: 1
          required:
            - firstName
            - lastName
      required:
        - id
        - email
        - name
      x-examples:
        Example:
          id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
          email: user@example.com
          name:
            firstName: string
            lastName: string
          value:
            id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
            email: user@example.com
            name:
              firstName: string
              lastName: string
  securitySchemes:
    authorization:
      type: http
      scheme: bearer
      description: ''
  responses: {}
