openapi: 3.0.0
info:
  title: Confirmation 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/hydrophone/blob/master/LICENSE
  x-tidepool-service: https://github.com/tidepool-org/hydrophone
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
tags:
  - name: Internal
    description: APIs intended for internal use by Tidepool.
  - name: Confirmations
    description: Manage confirmations for account creation, sharing invites, etc.
paths:
  /confirm/send/signup/{userId}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
    post:
      operationId: SendAccountSignupConfirmation
      summary: Send Account Signup Confirmation
      description: Sends account signup confirmation email.
      requestBody:
        $ref: '#/components/requestBodies/ConfirmationUpsert'
      responses:
        '200':
          $ref: '#/components/responses/ConfirmationSuccess'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '401':
          $ref: '#/components/responses/ConfirmationError'
        '403':
          $ref: '#/components/responses/ConfirmationError'
        '500':
          $ref: '#/components/responses/ConfirmationError'
      tags:
        - Confirmations
      security:
        - sessionToken: []
  /confirm/resend/signup/{email}:
    parameters:
      - $ref: '#/components/parameters/email.v1'
    post:
      operationId: ResendAccountSignup
      summary: Resend account signup confirmation email
      description: >-
        If a user didn't receive the confirmation email and logs in, they're
        directed to the confirmation-required page which can offer to resend the
        confirmation email.
      responses:
        '200':
          $ref: '#/components/responses/ConfirmationSuccess'
        '404':
          $ref: '#/components/responses/ConfirmationError'
        '500':
          $ref: '#/components/responses/ConfirmationError'
      security: []
      tags:
        - Confirmations
  /confirm/accept/signup/{key}:
    parameters:
      - $ref: '#/components/parameters/key.v1'
    put:
      operationId: ConfirmAccountSignup
      summary: Accept Account Signup
      description: >-
        Marks the account as having been verified. This would be PUT by the web
        page at the link in the signup email.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/acceptance.v1'
      responses:
        '200':
          $ref: '#/components/responses/ConfirmationSuccess'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '409':
          $ref: '#/components/responses/ConfirmationError'
        '500':
          $ref: '#/components/responses/ConfirmationError'
      security: []
      tags:
        - Confirmations
  /confirm/dismiss/signup/{userId}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
    put:
      operationId: DismissAccountSignup
      summary: Dismiss Account Signup
      description: >-
        In the event that someone uses the wrong email address, the receiver
        could explicitly dismiss a signup
      requestBody:
        $ref: '#/components/requestBodies/ConfirmationLookup'
      responses:
        '200':
          $ref: '#/components/responses/ConfirmationSuccess'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '404':
          $ref: '#/components/responses/ConfirmationError'
      security: []
      tags:
        - Confirmations
  /confirm/signup/{userId}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
    get:
      operationId: GetAccountSignupConfirmation
      summary: Get Account Signup Confirmation
      description: Fetch latest account signup confirmation for the provided userId
      responses:
        '200':
          $ref: '#/components/responses/Confirmation'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '401':
          $ref: '#/components/responses/ConfirmationError'
        '404':
          $ref: '#/components/responses/ConfirmationError'
        '500':
          $ref: '#/components/responses/ConfirmationError'
      tags:
        - Confirmations
      security:
        - sessionToken: []
    post:
      operationId: UpsertAccountSignupConfirmation
      summary: Upsert Account Signup Confirmation
      description: Add or refresh an account signup confirmation for the provided userId
      requestBody:
        $ref: '#/components/requestBodies/ConfirmationUpsert'
      responses:
        '200':
          $ref: '#/components/responses/Confirmation'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '403':
          $ref: '#/components/responses/ConfirmationError'
        '404':
          $ref: '#/components/responses/ConfirmationError'
        '500':
          $ref: '#/components/responses/ConfirmationError'
      tags:
        - Confirmations
      security:
        - sessionToken: []
    put:
      operationId: CancelAccountSignupConfirmation
      summary: Cancel Account Signup
      description: Cancels the account signup.
      requestBody:
        $ref: '#/components/requestBodies/ConfirmationLookup'
      responses:
        '200':
          $ref: '#/components/responses/ConfirmationSuccess'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '401':
          $ref: '#/components/responses/ConfirmationError'
        '403':
          $ref: '#/components/responses/ConfirmationError'
        '404':
          $ref: '#/components/responses/ConfirmationError'
      security: []
      tags:
        - Confirmations
  /confirm/forgot/{email}:
    parameters:
      - $ref: '#/components/parameters/email.v1'
    post:
      operationId: SendPasswordReset
      summary: Send Password Reset Email
      description: >-
        If the request is correctly formed, always returns a 200, even if the
        email address was not found (this way it can't be used to validate email
        addresses).

        If the email address is found in the Tidepool system, this will:
          - Create a confirm record and a random key
          - Send an email with a link containing the key
      responses:
        '200':
          $ref: '#/components/responses/ConfirmationSuccess'
        '400':
          $ref: '#/components/responses/ConfirmationError'
      security: []
      tags:
        - Confirmations
  /confirm/accept/forgot:
    put:
      operationId: AcceptPasswordChange
      summary: Accept password change
      description: >-
        Accept the password change

        This endpoint will be invoked by the lost password screen with the key
        that was included in the URL of the lost password screen.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/password.v1'
      responses:
        '200':
          $ref: '#/components/responses/ConfirmationError'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '401':
          $ref: '#/components/responses/ConfirmationError'
        '404':
          $ref: '#/components/responses/ConfirmationError'
      security: []
      tags:
        - Confirmations
  /confirm/send/invite/{userId}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
    post:
      operationId: SendCareTeamInvite
      summary: Send Invitation to Join Care Team
      description: >-
        Sends an invitation to join the care team of the user identified by
        `userId`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/invitation.v1'
      responses:
        '200':
          $ref: '#/components/responses/Confirmation'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '401':
          $ref: '#/components/responses/ConfirmationError'
        '500':
          $ref: '#/components/responses/ConfirmationError'
      security:
        - sessionToken: []
      tags:
        - Confirmations
  /confirm/accept/invite/{userId}/{invitedBy}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
      - $ref: '#/components/parameters/invitedbyuser.v1'
    put:
      operationId: AcceptCareTeamInvite
      summary: Accept Invitation to Join Care Team
      description: Accepts the invitation to join a care team.
      requestBody:
        $ref: '#/components/requestBodies/ConfirmationLookup'
      responses:
        '200':
          $ref: '#/components/responses/ConfirmationSuccess'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '403':
          $ref: '#/components/responses/ConfirmationError'
        '404':
          $ref: '#/components/responses/ConfirmationError'
        '500':
          $ref: '#/components/responses/ConfirmationError'
      security:
        - sessionToken: []
      tags:
        - Confirmations
  /confirm/invite/{userId}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
    get:
      operationId: GetSentInvitations
      summary: Get Pending Care Team Invitations
      description: >-
        Returns the still-pending invitations for an account you own or are an
        admin of.

        These are the invitations you have sent that have not been accepted.
        There is no way to tell if an invitation has been ignored.
      responses:
        '200':
          $ref: '#/components/responses/ConfirmationList'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '401':
          $ref: '#/components/responses/ConfirmationError'
        '500':
          $ref: '#/components/responses/ConfirmationError'
      tags:
        - Confirmations
      security:
        - sessionToken: []
  /confirm/invitations/{userId}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
    get:
      operationId: GetReceivedInvitations
      summary: Get Received Care Team Invitations
      description: >-
        Get list of received invitations for logged in user. These are
        invitations that have been sent to this user but not yet acted upon.
      responses:
        '200':
          $ref: '#/components/responses/ConfirmationList'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '401':
          $ref: '#/components/responses/ConfirmationError'
      tags:
        - Confirmations
      security:
        - sessionToken: []
  /confirm/dismiss/invite/{userId}/{invitedBy}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
      - $ref: '#/components/parameters/invitedbyuser.v1'
    put:
      operationId: DismissInvite
      summary: Dismiss Care Team Invitation
      description: Declines the invitation to join a care team.
      requestBody:
        $ref: '#/components/requestBodies/ConfirmationLookup'
      responses:
        '200':
          $ref: '#/components/responses/ConfirmationSuccess'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '401':
          $ref: '#/components/responses/ConfirmationError'
        '404':
          $ref: '#/components/responses/ConfirmationError'
        '500':
          $ref: '#/components/responses/ConfirmationError'
      tags:
        - Confirmations
      security:
        - sessionToken: []
  /confirm/{userId}/invited/{invitedBy}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
      - $ref: '#/components/parameters/invitedbyemail.v1'
    put:
      operationId: CancelInvite
      summary: Cancel Care Team Invitation
      description: Cancels an invitation that has been sent to an email address.
      responses:
        '200':
          $ref: '#/components/responses/ConfirmationSuccess'
        '400':
          $ref: '#/components/responses/ConfirmationError'
        '401':
          $ref: '#/components/responses/ConfirmationError'
        '500':
          $ref: '#/components/responses/ConfirmationError'
      tags:
        - Confirmations
      security:
        - sessionToken: []
components:
  schemas:
    Acceptance:
      $ref: '#/components/schemas/acceptance.v1'
    Password:
      $ref: '#/components/schemas/password.v1'
    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
    clinicId.v1:
      title: Clinic ID
      description: Clinic identifier.
      type: string
      minLength: 24
      maxLength: 24
      pattern: ^[a-f0-9]{24}$
      readOnly: true
      example: 2fe2488217ee43e1b2e83c2f
    upsert.v1:
      title: Confirmation Lookup
      type: object
      properties:
        clinicId:
          $ref: '#/components/schemas/clinicId.v1'
        invitedBy:
          $ref: '#/components/schemas/tidepooluserid'
    error.v1:
      type: object
      title: Confirmation Error
      description: Error response.
      required:
        - code
        - reason
      properties:
        code:
          type: integer
          format: int32
          minimum: 100
        error:
          type: integer
        reason:
          type: string
    emailaddress.v1:
      title: Email Address
      description: >-
        An email address, as specified by [RFC
        5322](https://datatracker.ietf.org/doc/html/rfc5322).
      type: string
      format: email
      minLength: 6
      example: example@tidepool.org
      x-go-type: string
    key.v1:
      title: Confirmation key that uniquely identifies each confirmation
      type: string
      minLength: 32
      maxLength: 32
      example: Sds2PHMALZrmt++JyD5mIjLkZruJldiM
    password.v1:
      title: Password
      type: string
      format: password
      description: Password
      minLength: 8
      maxLength: 72
      pattern: ^\S{8,72}$
      example: correctbatteryhorsestaple
      x-go-type: string
    birthday.v1:
      title: Birthday
      type: string
      format: date
      example: '2012-08-30'
      x-go-type: string
    acceptance.v1:
      title: Confirmation Acceptance
      type: object
      properties:
        password:
          $ref: '#/components/schemas/password.v1'
        birthday:
          $ref: '#/components/schemas/birthday.v1'
      required:
        - password
        - birthday
    lookup.v1:
      title: Confirmation Lookup
      type: object
      properties:
        key:
          $ref: '#/components/schemas/key.v1'
      required:
        - key
    confirmation-type.v1:
      title: Confirmation Type
      type: string
      enum:
        - password_reset
        - careteam_invitation
        - clinician_invitation
        - signup_confirmation
        - no_account
    status.v1:
      title: Confirmation Status
      type: string
      enum:
        - pending
        - completed
        - canceled
        - declined
    datetime.v1:
      title: Date/Time
      description: >-
        [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) / [ISO
        8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp
        _with_ timezone information
      type: string
      format: date-time
      example: '2017-02-06T02:37:46Z'
      x-go-type: string
    diagnosisdate.v1:
      title: Diagnosis Date
      type: string
      format: date
      pattern: ^\d{4}-\d{2}-\d{2}$
      example: '2013-05-09'
      x-go-type: string
    patientprofile.v1:
      title: Patient User Profile
      type: object
      properties:
        birthday:
          $ref: '#/components/schemas/birthday.v1'
        diagnosisDate:
          $ref: '#/components/schemas/diagnosisdate.v1'
        isOtherPerson:
          type: boolean
          example: false
        fullName:
          type: string
          example: James Jellyfish
    creatorprofile.v1:
      title: Creator user profile
      type: object
      properties:
        fullName:
          type: string
        patient:
          $ref: '#/components/schemas/patientprofile.v1'
      required:
        - fullName
        - patient
    creator.v1:
      title: Creator
      type: object
      properties:
        userid:
          $ref: '#/components/schemas/tidepooluserid'
        profile:
          $ref: '#/components/schemas/creatorprofile.v1'
      required:
        - userid
        - profile
    restrictions.v1:
      title: Acceptance restrictions
      type: object
      properties:
        canAccept:
          type: boolean
          description: Whether the invite can be accepted by the current user
        requiredIdp:
          type: string
          description: >-
            Set if the user must be authenticated against a specific identity
            provider before they are able to accept the invite
      required:
        - canAccept
    expiresAt.v1:
      title: Expiration Time
      type: string
      format: date-time
      description: If specified, the invitation will expire at the given date and time.
      example: '2024-01-30T08:11:00Z'
    confirmation.v1:
      title: Confirmation
      type: object
      properties:
        key:
          $ref: '#/components/schemas/key.v1'
        type:
          $ref: '#/components/schemas/confirmation-type.v1'
        status:
          $ref: '#/components/schemas/status.v1'
        email:
          $ref: '#/components/schemas/emailaddress.v1'
        creatorId:
          $ref: '#/components/schemas/tidepooluserid'
        created:
          $ref: '#/components/schemas/datetime.v1'
        modified:
          $ref: '#/components/schemas/datetime.v1'
        creator:
          $ref: '#/components/schemas/creator.v1'
        context:
          type: string
        restrictions:
          $ref: '#/components/schemas/restrictions.v1'
        expiresAt:
          $ref: '#/components/schemas/expiresAt.v1'
      required:
        - key
        - type
        - status
        - email
        - creatorId
        - created
    base.v1:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
          description: A toggle for disabling the alert.
    unitsmgdl.v1:
      title: Blood Unit (mg/dL)
      type: string
      enum:
        - mg/dL
        - mg/dl
      example: mg/dL
      x-tags:
        - Data
    valuemgdl.v1:
      title: Blood Value (mg/dL)
      description: An integer value representing a `mg/dL` value.
      type: integer
      format: int32
      minimum: 0
      maximum: 1000
      example: 105
      x-tags:
        - Data
    glucosemgdl.v1:
      title: Blood Glucose (mg/dL)
      description: Blood glucose value, in `mg/dL`
      type: object
      properties:
        units:
          $ref: '#/components/schemas/unitsmgdl.v1'
        value:
          $ref: '#/components/schemas/valuemgdl.v1'
      required:
        - units
        - value
      x-tags:
        - Data
    unitsmmol.v1:
      title: Blood Unit (mmol/L)
      type: string
      enum:
        - mmol/L
        - mmol/l
      example: mmol/L
      x-tags:
        - Data
    valuemmol.v1:
      title: Blood Value (mmol/L)
      description: A floating point value representing a `mmol/L` value.
      type: number
      format: float
      minimum: 0
      example: 5.5
      x-tags:
        - Data
    glucosemmol.v1:
      title: Blood Glucose (mmol/L)
      description: Blood glucose value, in `mmol/L`
      type: object
      properties:
        units:
          $ref: '#/components/schemas/unitsmmol.v1'
        value:
          $ref: '#/components/schemas/valuemmol.v1'
      required:
        - units
        - value
      x-tags:
        - Data
    glucose.v1:
      title: Blood Glucose
      description: Blood glucose value, in `mg/dL` or `mmol/L`
      oneOf:
        - $ref: '#/components/schemas/glucosemgdl.v1'
        - $ref: '#/components/schemas/glucosemmol.v1'
      x-tags:
        - Data
    glucosethreshold.v1:
      type: object
      properties:
        threshold:
          $ref: '#/components/schemas/glucose.v1'
      required:
        - threshold
    delay.v1:
      type: object
      properties:
        delay:
          type: integer
          default: 0
          minimum: 0
          maximum: 120
          description: Duration in minutes to wait before alerting.
    repeat.v1:
      type: object
      properties:
        repeat:
          type: integer
          default: 0
          minimum: 0
          maximum: 240
          description: |-
            Duration in minutes, after which an alert will be repeated.
            A value of 0 disables the repeat functionality.
    alertsconfig.v1:
      type: object
      properties:
        urgentLow:
          allOf:
            - $ref: '#/components/schemas/base.v1'
            - $ref: '#/components/schemas/glucosethreshold.v1'
            - type: object
              description: >-
                Blood glucose measurements at or below this value will trigger
                an immediate and urgent alert.
        low:
          allOf:
            - $ref: '#/components/schemas/base.v1'
            - $ref: '#/components/schemas/delay.v1'
            - $ref: '#/components/schemas/repeat.v1'
            - $ref: '#/components/schemas/glucosethreshold.v1'
            - type: object
              description: >-
                Blood glucose measurements at or below this value will trigger
                an alert.
        high:
          allOf:
            - $ref: '#/components/schemas/base.v1'
            - $ref: '#/components/schemas/delay.v1'
            - $ref: '#/components/schemas/repeat.v1'
            - $ref: '#/components/schemas/glucosethreshold.v1'
            - type: object
              description: >-
                Blood glucose measurements at or above this value will trigger
                an alert.
        noCommunication:
          allOf:
            - $ref: '#/components/schemas/base.v1'
            - $ref: '#/components/schemas/delay.v1'
            - type: object
              description: An alert sent when issues prevent the display of CGM data.
        notLooping:
          allOf:
            - $ref: '#/components/schemas/base.v1'
            - $ref: '#/components/schemas/delay.v1'
            - type: object
              description: An alert sent when the Tidepool Loop app is unable to loop.
      minProperties: 1
      description: >-
        Configuration for alerts triggered in response to the status of a user's
        device and data.
    invitation.v1:
      title: Care Team Invitation
      type: object
      properties:
        email:
          $ref: '#/components/schemas/emailaddress.v1'
        permissions:
          type: object
          properties:
            note:
              type: object
            upload:
              type: object
            view:
              type: object
          example:
            note: {}
            upload: {}
            view: {}
        nickname:
          description: A user-friendly name for the recipient of the invitation.
          type: string
          example: Julia
        alertsConfig:
          $ref: '#/components/schemas/alertsconfig.v1'
      required:
        - email
        - permissions
    list.v1:
      title: Confirmation list
      type: array
      items:
        $ref: '#/components/schemas/confirmation.v1'
  parameters:
    userId:
      $ref: '#/components/parameters/tidepooluserid'
    email:
      $ref: '#/components/parameters/email.v1'
    key:
      $ref: '#/components/parameters/key.v1'
    invitedByUser:
      $ref: '#/components/parameters/invitedbyuser.v1'
    invitedByEmail:
      $ref: '#/components/parameters/invitedbyemail.v1'
    tidepooluserid:
      description: Tidepool User ID
      name: userId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/tidepooluserid'
    email.v1:
      description: Confirmation Email
      name: email
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/emailaddress.v1'
    key.v1:
      description: Confirmation Key
      name: key
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/key.v1'
    invitedbyuser.v1:
      description: Invited by User ID
      name: invitedBy
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/tidepooluserid'
    invitedbyemail.v1:
      description: Invited by Email Address
      name: invitedBy
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/emailaddress.v1'
  securitySchemes:
    sessionToken:
      description: Tidepool Session Token
      type: apiKey
      name: X-Tidepool-Session-Token
      in: header
  requestBodies:
    ConfirmationLookup:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/lookup.v1'
    ConfirmationUpsert:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/upsert.v1'
  responses:
    Confirmation:
      description: Single confirmation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/confirmation.v1'
    ConfirmationList:
      description: List of confirmations
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/list.v1'
    ConfirmationSuccess:
      description: Success
    ConfirmationError:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error.v1'
