openapi: 3.0.0
info:
  title: Authorization API
  version: '1.0'
  description: >-
    The Tidepool API is an HTTP REST API used by Tidepool clients use to
    communicate with the Tidepool Platform.


    For more information, see the [Getting Started](../docs/quick-start.md)
    section.
  termsOfService: https://developer.tidepool.org/terms-of-use
  contact:
    name: API Support
    url: https://support.tidepool.org/
    email: support@tidepool.org
  license:
    name: BSD-2-Clause
    url: https://github.com/tidepool-org/gatekeeper/blob/develop/LICENSE
  x-tidepool-service: https://github.com/tidepool-org/gatekeeper
servers:
  - url: https://external.integration.tidepool.org
    description: integration
  - url: https://api.tidepool.org
    description: production
  - url: https://dev1.dev.tidepool.org
    description: dev1
  - url: https://qa1.development.tidepool.org
    description: qa1
  - url: https://qa2.development.tidepool.org
    description: qa2
security:
  - sessionToken: []
tags:
  - name: Internal
    description: APIs intended for internal use by Tidepool.
  - name: Authorization
    description: >-
      List, create and manage authorizations that grant access to another user's
      diabetes data.
paths:
  /access/groups/{userId}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
    get:
      operationId: GetGroupsForUser
      summary: Get Groups for User
      description: Retrieve all groups accessible to the user `userId`.
      responses:
        '200':
          $ref: '#/components/responses/GroupPermissions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - Authorization
  /access/{sharerId}:
    parameters:
      - $ref: '#/components/parameters/tidepoolsharerid.v1'
    get:
      operationId: GetUsersInGroup
      summary: Get Users in Group
      description: Retrieve all users that have access to group `sharerId`.
      responses:
        '200':
          $ref: '#/components/responses/GroupPermissions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - Authorization
  /access/{sharerId}/{userId}:
    parameters:
      - $ref: '#/components/parameters/tidepoolsharerid.v1'
      - $ref: '#/components/parameters/tidepooluserid'
    get:
      operationId: GetPermissionsForUser
      summary: Get User Permissions in Group
      description: Retrieve permissions of individual user `userId` in group `sharerId`.
      responses:
        '200':
          $ref: '#/components/responses/UserPermissions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - Authorization
    post:
      operationId: GrantPermissionsInGroup
      summary: Update Permissions for User in Group
      description: >-
        Update permissions of individual user `userId` in group `sharerId`. The
        permissions provided in the request body replace all existing
        permissions for that user. Therefore to delete a permission, submit the
        request body without that permission.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/modifyuserpermissions.v1'
      responses:
        '200':
          $ref: '#/components/responses/UserPermissions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - Authorization
components:
  securitySchemes:
    sessionToken:
      description: Tidepool Session Token
      type: apiKey
      name: X-Tidepool-Session-Token
      in: header
  responses:
    UserPermissions:
      description: Access permissions of a user
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/userpermissions.v1'
    GroupPermissions:
      description: Access permissions of one or more users within a group
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/grouppermissions.v1'
    BadRequest:
      description: Bad Request
    Unauthorized:
      description: Unauthorized
    Forbidden:
      description: Forbidden
    NotFound:
      description: Not Found
    ServerError:
      description: Server Error
  schemas:
    tidepooluserid:
      type: string
      title: Tidepool User ID
      pattern: >-
        ^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
      description: >-
        String representation of a Tidepool User ID. Old style IDs are 10-digit
        strings consisting of only hexadeximcal digits. New style IDs are
        36-digit [UUID
        v4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random))
      readOnly: true
      x-go-type: string
    permission.v1:
      title: Permission
      description: >-
        The presence of this object indicates that the user has been granted the
        named permission.
      type: object
      example: {}
    owner.v1:
      title: Owner
      description: Full account owner access permission.
      type: object
      properties:
        root:
          $ref: '#/components/schemas/permission.v1'
      example:
        root: {}
    custodian.v1:
      title: Custodian
      description: Full custodial permission.
      type: object
      properties:
        custodian:
          $ref: '#/components/schemas/permission.v1'
      example:
        custodian: {}
    view.v1:
      title: View
      description: Permission to view diabetes data in the account.
      type: object
      properties:
        view:
          $ref: '#/components/schemas/permission.v1'
      example:
        view: {}
    note.v1:
      title: Notes
      description: Permission to view and manage notes in the account.
      type: object
      properties:
        note:
          $ref: '#/components/schemas/permission.v1'
      example:
        note: {}
    upload.v1:
      title: Upload
      description: Permission to upload diabetes data to the account.
      type: object
      properties:
        upload:
          $ref: '#/components/schemas/permission.v1'
      example:
        upload: {}
    userpermissions.v1:
      title: User Permissions
      description: Access permissions granted to a single user.
      type: object
      anyOf:
        - $ref: '#/components/schemas/owner.v1'
        - $ref: '#/components/schemas/custodian.v1'
        - $ref: '#/components/schemas/view.v1'
        - $ref: '#/components/schemas/note.v1'
        - $ref: '#/components/schemas/upload.v1'
      minProperties: 1
      example:
        note: {}
        upload: {}
        view: {}
    grouppermissions.v1:
      title: Group Permissions
      description: >-
        Access permissions granted to one or more users. The key for each child
        object is the Tidepool User ID of that user. The value of each child
        object is the set of permissions granted to that user.
      type: object
      additionalProperties:
        $ref: '#/components/schemas/userpermissions.v1'
      minProperties: 1
      example:
        d4206d26a6:
          root: {}
        305cabe660:
          note: {}
          view: {}
        7575613eca:
          view: {}
          note: {}
          upload: {}
        975ac5cc92:
          note: {}
          view: {}
    modifyuserpermissions.v1:
      title: Modify User Permissions
      type: object
      anyOf:
        - $ref: '#/components/schemas/view.v1'
        - $ref: '#/components/schemas/note.v1'
        - $ref: '#/components/schemas/upload.v1'
      minProperties: 1
      maxProperties: 3
  parameters:
    tidepooluserid:
      description: Tidepool User ID
      name: userId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/tidepooluserid'
    tidepoolsharerid.v1:
      description: Tidepool User ID of user who granted access
      name: sharerId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/tidepooluserid'
