openapi: 3.0.1
info:
  title: Agency APIs
  description: >-
    The agency endpoints allow a user with the appropriate scope (`agency_api`)
    and role (`agent`) to initiate consent requests for access to data owned by
    other users.
  version: v1
servers:
  - url: 'https://api.{env}.{tenant}.lenushealth.dev/agency/v1'
    variables:
      env:
        default: test
        enum:
          - test
          - sbx
      tenant:
        default: ggc
        enum:
          - ggc
        description: 'Available tenants'
paths:
  /createagencyinvite:
    post:
      tags:
        - agency
      summary: 'Send an invitation via email or SMS to an individual requesting agency over specific data scopes'
      description: >-
        The authenticated user must hold the `agent` role and access_token must request `agency_api` scope.
        
        
        The agency request can either be for the authenticated user or for an organization if the `organizationId` property is provided with a valid identifier.
        
        
        The request will trigger an email and/or SMS message to the specified recipient offering a clickable link that will allow the recipient to register for a new account or login to an existing account.  Once authenticated the user will be presented with details of the agency request and offered the chance to accept or reject it.  Once accepted a callback will be issued to `clientNotifyPath` (if provided) and the user will be redirected to `browserRedirectPath` (if provided).
      operationId: create-agency-invite-v1
      security:
        - bearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: 'object'
              required: 
                - 'requestedScopes'
              properties:
                email:
                  title: 'Email address'
                  description: An email address of an individual to receive agency request invitation.  This does not have to be the email address of an existing account.
                  type: 'string'
                  format: 'email'
                  example: 'john.doe@example.com'
                phoneNumber: 
                  title: 'Mobile Phone Number'
                  description: A mobile number to which the agency request invitation will be sent, the number _must_ use a complete international prefix such as +44, invalid numbers will result is not receiving the invitation SMS.
                  type: 'string'
                  example: '+447891234567'
                requestedScopes:
                  title: 'Requested scope list'
                  description: A list of data scopes for which consent is desired, both read and write scopes can be requested.  As scopes are granular it is important that related or correlated scopes are requested in groups, i.e. blood pressure
                  type: 'array'
                  example: 
                    - 'read.heart_rate'
                    - 'read.step_count'
                  items:
                    type: 'string'
                organizationId:
                  title: 'Organization Id'
                  description: An organization id for a known organization, if provided the agency request will be issued on behalf of the organization, acceptance of this by the user will result in all members of that organization gaining consent to query the given user's data
                  type: 'string'
                  format: 'uuid'
                clientNotifyPath:
                  type: 'string'
                  description: 'Provide a uri path starting with a /.  A GET request will be made to this path prefixed with the value of the client URI defined during client configuration within the developer portal. The request will contain a `subject` query parameter containing the unique identifier (`sub`) of the accepting user, this acts as a callback request to your service indicating that the user accepted your request for agency.'
                  example: '/redirectOnAgencyAcceptance'
                  format: 'uri-path'
                clientNotifyState:
                  type: 'string'
                  description: >-
                    Provide any optional custom state parameter value to include in the browser uri path defined in `clientNotifyPath`. Please do not present PII (personally identifiable information) or excessively long values.  
                    
                    
                    We would recommend that you consider using a unique key or hash value used to lookup specific user data when returning to your service.
                browserRedirectPath: 
                  type: 'string'
                  description: 'Provide a uri path starting with a / to redirect the user to after acceptance of the agency consent request.  This path will be prefixed with the client uri defined in the client issuing the agency request to form an absolute URI'
                  format: 'uri-path'
                  example: '/returnPath'
                browserRedirectState:
                  type: 'string'
                  description: 'Provide any optional state parameter value to include in the browser a uri path defined in `browserRedirectPath`'
      responses:
        '200':
          description: 'A message to the email and mobile phone number will provide instructions on accepting consent request'
        '401':
          description: 'The `access_token` is not valid, this maybe due to expiration or invalid audience of issuer'
        '403':
          description: 'Returns when the supplied bearer token does have the required scope (`agency_api`) or role (`agent`)'
  /querytoken:
    post:
      tags:
        - agency
      summary: >-
        Create an agency query token to retrieve data from an individual or user
        cohort
      description: >-
        The authenticated user must hold the `agent` role and access_token must request `agency_api` scope.
        
        
        In order to query health data for a user with whom you have consent you need to request a single use query token from this endpoint, the query token can then to used with the data samples endpoint to redirect data queries to a consented user instead of for the authenticated user
        
        
        The returned token _must_ be used by the same authenticated user (agent) when making a data query, with token is added as a request header named `agency-query-token`, further details are available within the data query API documentation.
      operationId: generate-agency-query-token-v1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                includeAll:
                  type: boolean
                  description: 'A flag indicating whether all subjects over which the caller has Agency are included, defaults to `false`'
                  example: false
                specificallyIncludedSubs:
                  type: array
                  description: 'An array of string, each one a subject to be included, defaults to empty'
                  items:
                    type: string
                    minItems: 0
                    format: 'uuid'
                specificallyExcludedSubs:
                  type: array
                  description: 'An array of string, each one a subject to be excluded, defaults to empty'
                  items:
                    type: string
                    minItems: 0
                    format: 'uuid'
      security:
        - bearer: []
      responses:
        '401':
          description: 'The `access_token` is not valid, this maybe due to expiration or invalid audience of issuer'
        '403':
          description: 'Returns when the supplied bearer token does have the required scope (`agency_api`) or role (`agent`)'
        '200':
          description: A token that can be used by the client acting on behalf of an agent querying the health data via the samples endpoint
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: string
                    example: '0vf7i1pef6DzFXeHyJw7r%2BcpG79SUbmS%2BinlRpFu6i8%3D'
  /claims:
    get:
      tags:
        - agency
      summary: Retrieve claims for consented users
      description: Retrieve a list of claims associated with users consented for the authenticated user
      operationId: retrieve-agency-claims-v1
      security:
        - bearer: []
      responses:
        '401':
          description: 'The `access_token` is not valid, this maybe due to expiration or invalid audience of issuer'
        '403':
          description: 'Returns when the supplied bearer token does have the required scope (`agency_api`) or role (`agent`)'      
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: array
                  items: 
                    type: object
                    properties:
                      type:
                        title: 'Type of claim'
                        example: 'given_name'
                      value:
                        title: 'Value of claim'
                        example: 'John'
  /querytokenresolution:
    get:
      tags:
        - internal
      summary: Resolve Query Token
      description: Resolves an agency query token
      operationId: query-token-resolution-v1
      security:
        - bearer: []
      parameters:
        - name: token
          in: query
          description: An agency query token
          required: true
          schema:
            type: string
      responses:
        '401':
          description: 'The `access_token` is not valid, this maybe due to expiration or invalid audience of issuer'
        '403':
          description: 'Returns when the supplied bearer token does have the required scope (`agency_api`) or role (`agent`)'
        '200':
          description: ''
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT