openapi: 3.0.0
info:
  title: Authentication 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/shoreline/blob/master/LICENSE'
  x-tidepool-service: 'https://github.com/tidepool-org/shoreline'
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: Users
    description: List and manage users.
paths:
  /auth/login:
    post:
      operationId: CreateSessionToken
      summary: Create New Session Token
      description: |-
        **This API is deprecated and will be removed by end of 2023.**
        Creates a new session token.
      responses:
        '200':
          $ref: '#/components/responses/UserWithToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: []
      tags:
        - Authentication
        - Internal
      deprecated: true
      x-internal: true
    get:
      operationId: RefreshSessionToken
      summary: Refresh Session Token
      description: |-
        **This API is deprecated and will be removed by end of 2023.**
        Refreshes an existing session token.
      responses:
        '200':
          $ref: '#/components/responses/TokenData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - sessionToken: []
      tags:
        - Authentication
        - Internal
      deprecated: true
      x-internal: true
  /auth/logout:
    post:
      operationId: Logout
      summary: Logout
      description: |-
        **This API is deprecated and will be removed by end of 2023.**
        Removes an existing session token. Returns success even if the session token does not exist.
      responses:
        '200':
          description: Success
      security: []
      tags:
        - Authentication
        - Internal
      deprecated: true
      x-internal: true
  /auth/user:
    get:
      operationId: GetCurrentUserInfo
      summary: Get Current User
      description: Returns user account information for the logger-in user.
      responses:
        '200':
          $ref: '#/components/responses/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - sessionToken: []
      tags:
        - Users
    post:
      operationId: CreateNewUser
      summary: Create New User Account
      description: |-
        **This API is deprecated and will be removed by end of 2023.**
        Creates a new user account.
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./auth/models/newuser.v1.yaml
      responses:
        '201':
          $ref: '#/components/responses/UserWithToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
      security: []
      tags:
        - Users
        - Internal
      deprecated: true
      x-internal: true
    put:
      operationId: UpdateCurrentUser
      summary: Update Current User Account
      description: Updates user account details of the logged-in user.
      requestBody:
        $ref: '#/components/requestBodies/UpdateUser'
      responses:
        '200':
          $ref: '#/components/responses/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - sessionToken: []
      tags:
        - Users
  /auth/users:
    get:
      operationId: GetUsers
      summary: Get Users
      description: 'Returns user accounts that match either the `role` or one of the Tidepool User IDs listed in the `id` list. The `role` and `id` parameters are mutually exclusive, and cannot be used together. The `role` parameter can be optionally combined with the `createdFrom` and/or `createdTo` parameters to limit the results to user accounts created within those dates.'
      parameters:
        - name: role
          in: query
          description: Filter users with the specific role
          schema:
            $ref: ./auth/models/role.v1.yaml
        - name: id
          in: query
          description: Filter users with one or more Tidepool User IDs
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: ./common/models/tidepooluserid.yaml
            minItems: 1
            maxItems: 200
            uniqueItems: true
        - name: createdFrom
          in: query
          description: Filter users created since specified date (inclusive)
          schema:
            $ref: ./auth/models/date.v1.yaml
        - name: createdTo
          in: query
          description: Filter users created until specified date (inclusive)
          schema:
            $ref: ./auth/models/date.v1.yaml
      responses:
        '200':
          $ref: '#/components/responses/Users'
        '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'
      security:
        - serverToken: []
      tags:
        - Users
        - Internal
  '/auth/user/{userId}':
    parameters:
      - $ref: ./common/parameters/tidepooluserid.yaml
    get:
      operationId: GetUserInfo
      summary: Get User
      description: Get information for the user identified by `userId`.
      responses:
        '200':
          $ref: '#/components/responses/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - sessionToken: []
      tags:
        - Users
    put:
      operationId: UpdateUser
      summary: Update User
      description: Updates the user identified by `userId`.
      requestBody:
        $ref: '#/components/requestBodies/UpdateUser'
      responses:
        '200':
          $ref: '#/components/responses/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - sessionToken: []
      tags:
        - Users
    delete:
      operationId: DeleteUser
      summary: Delete User
      description: 'Deletes the user identified by `userId`. The request body must provide the current password of the account to be deleted, unless the session token is a server token, or the account being deleted is a custodial account managed by the authenticated user.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./auth/models/deleteuser.v1.yaml
      responses:
        '202':
          description: Success
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: ''
      security:
        - sessionToken: []
        - serverToken: []
      tags:
        - Users
  '/auth/user/{userId}/user':
    parameters:
      - $ref: ./common/parameters/tidepooluserid.yaml
    post:
      operationId: CreateCustodialUser
      summary: Create Custodial User
      description: 'Creates a custodial user, that is, a user that has no independent login (no username, no password). The user identified by `userId` will be the `custodian` of this new custodial account. It will be granted the `custodial` permission on the new custodial user account.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./auth/models/newcustodialuser.v1.yaml
      responses:
        '201':
          $ref: '#/components/responses/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - sessionToken: []
      tags:
        - Users
  '/auth/login/{longtermkey}':
    parameters:
      - name: longtermkey
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: LongTermLogin
      summary: Login with a long term key
      description: Creates a long-lived session token.
      responses:
        '200':
          $ref: '#/components/responses/UserWithToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      security: []
      tags:
        - Authentication
        - Internal
  /auth/serverlogin:
    post:
      operationId: ServerLogin
      summary: Server to Server Login
      description: Server-to-server login
      parameters:
        - $ref: ./auth/parameters/tidepoolservername.v1.yaml
      responses:
        '200':
          $ref: '#/components/responses/ServerToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - Authentication
        - Internal
      security:
        - serverSecret: []
  /auth/token:
    get:
      operationId: CheckSessionToken
      summary: Check Session Token
      description: Checks the validity of a session token.
      responses:
        '200':
          $ref: '#/components/responses/TokenData'
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
        - Authentication
        - Internal
      security:
        - sessionToken: []
  '/auth/token/{token}':
    parameters:
      - name: token
        in: path
        required: true
        schema:
          $ref: ./common/models/tidepoolsessiontoken.v1.yaml
    get:
      operationId: ServerCheckToken
      summary: Server Check Token
      description: 'Checks the validity of a server token, provided via the `X-Tidepool-Session-Token` header, and then checks the validity of the session token provided via the `token` path parameter.'
      responses:
        '200':
          $ref: '#/components/responses/TokenData'
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
  /v1/device_check/verify:
    get:
      operationId: VerifyDeviceToken
      summary: Verify Device Token
      description: "Checks the validity of Apple's DeviceCheck token by calling Apple's server to verify it. For more details, see Apple's [developer documentation](https://developer.apple.com/documentation/devicecheck)."
      requestBody:
        $ref: '#/components/requestBodies/VerifyDeviceToken'
      responses:
        '200':
          $ref: '#/components/responses/DeviceTokenVerification'
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
        - Authentication
        - Internal
      security:
        - sessionToken: []
  '/v1/users/{userId}/restricted_tokens':
    parameters:
      - $ref: ./common/parameters/tidepooluserid.yaml
    get:
      operationId: ListUserRestrictedTokens
      summary: List All Restricted Tokens
      description: Lists all restricted tokens associated with the user `userId`. The list can be optionally paginated.
      parameters:
        - $ref: ./common/parameters/paginationpage.v1.yaml
        - $ref: ./common/parameters/paginationsize.v1.yaml
      responses:
        '200':
          $ref: '#/components/responses/RestrictedTokens'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
    post:
      operationId: CreateUserRestrictedToken
      summary: Create New Restricted Token
      description: Creates a new restricted token associated with the user `userId`.
      requestBody:
        $ref: '#/components/requestBodies/NewRestrictedToken'
      responses:
        '200':
          $ref: '#/components/responses/RestrictedToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
    delete:
      operationId: DeleteAllUserRestrictedTokens
      summary: Delete All Restricted Tokens
      description: Deletes all restricted tokens associated with the user `userId`.
      responses:
        '204':
          description: Success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
  '/v1/restricted_tokens/{tokenId}':
    parameters:
      - $ref: ./auth/parameters/restricted/tokenid.v1.yaml
    get:
      operationId: GetRestrictedToken
      summary: Get Restricted Token
      description: Returns the restricted token specified by the `tokenId`.
      responses:
        '200':
          $ref: '#/components/responses/RestrictedToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
    put:
      operationId: UpdateRestrictedToken
      summary: Update Restricted Token
      description: Updates the restricted token specified by the `tokenId`.
      requestBody:
        $ref: '#/components/requestBodies/UpdateRestrictedToken'
      responses:
        '200':
          $ref: '#/components/responses/RestrictedToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
    delete:
      operationId: DeleteRestrictedToken
      summary: Delete Restricted Token
      description: Delete the restricted token specified by `tokenId`.
      responses:
        '200':
          description: Success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
  '/auth/v1/users/{userId}/provider_sessions':
    parameters:
      - $ref: ./common/parameters/tidepooluserid.yaml
    get:
      operationId: ListUserDataProviderSessions
      summary: List Data Provider Sessions
      description: 'Lists all data provider sessions associated with the user `userId`. The list can be optionally paginated, and filtered by provider name and/or type.'
      parameters:
        - $ref: ./common/parameters/paginationpage.v1.yaml
        - $ref: ./common/parameters/paginationsize.v1.yaml
        - $ref: ./auth/parameters/providers/providerName.v1.yaml
        - $ref: ./auth/parameters/providers/provider-type.v1.yaml
      responses:
        '200':
          $ref: '#/components/responses/ProviderSessions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
    post:
      operationId: CreateUserDataProviderSession
      summary: Create New Data Provider Sessions
      description: Creates a new data provider session associated with the user `userId`.
      requestBody:
        $ref: '#/components/requestBodies/NewProviderSession'
      responses:
        '200':
          $ref: '#/components/responses/ProviderSession'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
    delete:
      operationId: DeleteAllUserDataProviderSessions
      summary: Delete All Data Provider Sessions
      description: Deletes all data provider sessions associated with the user `userId`.
      responses:
        '204':
          description: Success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
  '/auth/v1/provider_sessions/{sessionId}':
    parameters:
      - $ref: ./auth/parameters/providers/sessionid.v1.yaml
    get:
      operationId: GetUserDataProviderSession
      summary: Get Data Provider Session
      description: Returns the data provider session specified by the `sessionId`.
      responses:
        '200':
          $ref: '#/components/responses/ProviderSession'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
    put:
      operationId: UpdateUserDataProviderSession
      summary: Update Data Provider Session
      description: Updates the data provider session specified by the `sessionId`.
      requestBody:
        $ref: '#/components/requestBodies/UpdateProviderSession'
      responses:
        '200':
          $ref: '#/components/responses/ProviderSession'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
    delete:
      operationId: DeleteUserDataProviderSession
      summary: Delete Data Provider Session
      description: Delete the data provider session specified by `sessionId`.
      responses:
        '200':
          description: Success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Authentication
        - Internal
      security:
        - serverToken: []
  '/v1/users/{userId}/device_tokens':
    parameters:
      - $ref: ./common/parameters/tidepooluserid.yaml
    post:
      operationId: CreateDeviceTokenForUser
      summary: Post Device Token
      description: Stores a token used to send notifications to a device such as a mobile phone.
      requestBody:
        $ref: '#/components/requestBodies/DeviceToken'
      responses:
        '200':
          description: 200 OK
        '400':
          $ref: ./common/responses/badrequest.v1.yaml
        '403':
          $ref: ./common/responses/forbidden.v1.yaml
      security:
        - sessionToken: []
      tags:
        - Internal
components:
  securitySchemes:
    basicAuth:
      $ref: ./common/security/basicauth.v1.yaml
    sessionToken:
      $ref: ./common/security/tidepoolsessiontoken.v1.yaml
    serverToken:
      $ref: ./common/security/tidepoolservertoken.v1.yaml
    serverSecret:
      $ref: ./common/security/tidepoolserversecret.v1.yaml
  requestBodies:
    UpdateUser:
      description: Updated user details
      content:
        application/json:
          schema:
            $ref: ./auth/models/updateuser.v1.yaml
    VerifyDeviceToken:
      description: Verify device token
      content:
        application/json:
          schema:
            type: object
            properties:
              device_token:
                type: string
                minLength: 1
            required:
              - device_token
    NewRestrictedToken:
      description: New restricted token
      content:
        application/json:
          schema:
            $ref: ./auth/models/restricted/newtoken.v1.yaml
    UpdateRestrictedToken:
      description: Updated restricted token
      content:
        application/json:
          schema:
            $ref: ./auth/models/restricted/updatetoken.v1.yaml
    NewProviderSession:
      description: New provider session
      content:
        application/json:
          schema:
            $ref: ./auth/models/providers/newsession.v1.yaml
    UpdateProviderSession:
      description: Updated provider session
      content:
        application/json:
          schema:
            $ref: ./auth/models/providers/updatesession.v1.yaml
    DeviceToken:
      description: Device token used for sending push notifications to a mobile device.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: ./auth/models/devicetoken-apple.v1.yaml
  responses:
    User:
      description: Tidepool User Account
      content:
        application/json:
          schema:
            $ref: ./auth/models/user.v1.yaml
    Users:
      description: Tidepool User Accounts
      content:
        application/json:
          schema:
            $ref: ./auth/models/users.v1.yaml
    UserWithToken:
      description: Tidepool User Account with Token
      headers:
        X-Tidepool-Session-Token:
          $ref: ./common/headers/tidepoolsessiontoken.v1.yaml
      content:
        application/json:
          schema:
            $ref: ./auth/models/user.v1.yaml
    TokenData:
      description: Token Data
      headers:
        X-Tidepool-Session-Token:
          $ref: ./common/headers/tidepoolsessiontoken.v1.yaml
      content:
        application/json:
          schema:
            $ref: ./auth/models/tokendata.v1.yaml
    ServerToken:
      description: Server Token
      headers:
        X-Tidepool-Session-Token:
          $ref: ./common/headers/tidepoolsessiontoken.v1.yaml
    DeviceTokenVerification:
      description: Device token verification response
      content:
        application/json:
          schema:
            type: object
            properties:
              valid:
                type: boolean
            required:
              - valid
    RestrictedToken:
      description: Restricted Token
      content:
        application/json:
          schema:
            $ref: ./auth/models/restricted/token.v1.yaml
    RestrictedTokens:
      description: Restricted Tokens
      content:
        application/json:
          schema:
            $ref: ./auth/models/restricted/tokens.v1.yaml
    ProviderSession:
      description: Provider Session
      content:
        application/json:
          schema:
            $ref: ./auth/models/providers/session.v1.yaml
    ProviderSessions:
      description: Provider Sessions
      content:
        application/json:
          schema:
            $ref: ./auth/models/providers/sessions.v1.yaml
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            allOf:
              - $ref: ./auth/models/error.v1.yaml
              - type: object
                properties:
                  code:
                    type: integer
                    enum:
                      - 401
                  reason:
                    type: string
                    enum:
                      - No user matched the given details
                      - A server token is required
                      - Not authorized for requested operation
                      - Wrong password
                      - No X-Tidepool-Session-Token was found
                required:
                  - code
                  - reason
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            allOf:
              - $ref: ./auth/models/error.v1.yaml
              - type: object
                properties:
                  code:
                    type: integer
                    enum:
                      - 400
                  reason:
                    type: string
                    enum:
                      - The role specified is invalid
                      - Not all required details were given
                      - Invalid user details were given
                      - Missing id and/or password
                required:
                  - code
                  - reason
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            allOf:
              - $ref: ./auth/models/error.v1.yaml
              - type: object
                properties:
                  code:
                    type: integer
                    enum:
                      - 403
                  reason:
                    type: string
                    enum:
                      - The user hasn't verified this account yet
                required:
                  - code
                  - reason
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            allOf:
              - $ref: ./auth/models/error.v1.yaml
              - type: object
                properties:
                  code:
                    type: integer
                    enum:
                      - 404
                  reason:
                    type: string
                    enum:
                      - Requested account was not found
                required:
                  - code
                  - reason
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            allOf:
              - $ref: ./auth/models/error.v1.yaml
              - type: object
                properties:
                  code:
                    type: integer
                    enum:
                      - 409
                  reason:
                    type: string
                    enum:
                      - User already exists
                required:
                  - code
                  - reason
    ServerError:
      description: Server Error
      content:
        application/json:
          schema:
            allOf:
              - $ref: ./auth/models/error.v1.yaml
              - type: object
                properties:
                  code:
                    type: integer
                    enum:
                      - 500
                  reason:
                    type: string
                    enum:
                      - Error finding user
                      - Error generating the token
                      - Error updating user
                      - Error updating token
                required:
                  - code
                  - reason