openapi: 3.0.3
tags:
  - name: Tokens
    description: Tokens for users who access 3rd party systems
x-tagGroups:
  - name: TOKENS
    tags:
      - Tokens
info:
  title: Utility services in the TonicDM API
  version: 0.0.1
  description: Utility services in the TonicDM API
  contact:
    name: Reg Prentice
    url: https://developers-internal.tonicdm.com
    email: apisupport@tonicdm.com
  termsOfService: http://www.tonicdm.com/terms
  license:
    name: Proprietary
    url: https://www.tonicdm.com/license-api
servers:
  - url: https://us-api.tonicdm.com
    description: Server located in the USA
  - url: https://de-api.tonicdm.com
    description: Server located in Germany
  - url: https://ie-api.tonicdm.com
    description: Server located in Ireland
security:
  - OAuth2:
      - read
      - write
  - apiKeyAuth: []
paths:
  /tokens/token:
    description: Tokens for users who access 3rd party systems.
    get:
      x-internal: true
      summary: Get 3rd Party Token
      operationId: get-3rdparty-token
      description: >
        Get a token to be used by the back end to access a 3rd party system on
        behalf of a user.
      tags:
        - Tokens
      parameters:
        - $ref: '#/components/parameters/platform'
        - in: query
          name: source
          description: The project whose data will be moved. This project will be deleted.
          schema:
            type: string
            format: email
          required: true
      responses:
        '200':
          description: >-
            Successfully read the resource you requested. One or more records
            are returned in the form of an array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
              examples:
                Token:
                  $ref: '#/components/examples/Token'
        '204':
          $ref: '#/components/responses/NoContentSuccess'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/NoAccessError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceededError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
      x-amazon-apigateway-integration:
        requestParameters:
          integration.request.header.platform: method.request.header.platform
          integration.request.header.emailAddress: method.request.header.emailAddress
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Read access to protected resources
            write: Write access to protected resources
    apiKeyAuth:
      type: apiKey
      in: query
      name: X-API-KEY
  parameters:
    platform:
      name: platform
      in: query
      schema:
        type: string
        enum:
          - egnyte
          - sharepoint
          - msgraph
          - procore
          - acc
      description: Defines the cloud platform to use.
      required: true
      example: egnyte
  schemas:
    Platform:
      title: Platform
      description: >-
        The name of the 3rd party platform that the TonicDM user or organization
        is connected to.
      type: string
      enum:
        - egnyte
        - sharepoint
        - msgraph
        - procore
      default: active
    Token:
      title: Token
      type: object
      description: >
        Used by the back end (never exposed to the front end) to manage OAuth2
        tokens that the The TonicDM back end uses to access 3rd party services
        on behalf of the user.

        This will always be an *access* token, not a refresh token, since
        refresh tokens are handled internally to the service.
      properties:
        platform:
          $ref: '#/components/schemas/Platform'
        emailAddress:
          description: The email address of the user requesting the token.
          type: string
          format: email
        token:
          description: The OAuth2 access token.
          type: string
          readOnly: true
        expiryDatetime:
          description: The date and time this token will expire.
          type: string
          format: date-time
          readOnly: true
    Errors:
      title: Errors
      type: object
      required:
        - errors
      properties:
        errors:
          description: x
          type: array
          minItems: 1
          items:
            required:
              - code
              - message
            properties:
              code:
                description: x
                type: string
              message:
                description: x
                type: string
              source:
                description: x
                title: ErrorSource
                required:
                  - location
                  - name
                properties:
                  location:
                    description: x
                    type: string
                    enum:
                      - path
                      - query
                      - body
                      - header
                  name:
                    type: string
                    description: The name of the property or parameter causing the error
                  path:
                    type: string
                    description: >-
                      JSON path targeting the source of error (only used when
                      location is `body`)
  examples:
    Token:
      summary: Sample data that would be returned for one 3rd Party Token.
      value:
        platform: egnyte
        emailAddress: reg@pacific-architects.com
        token: 1234567890abcdef
        expiryDatetime: '2022-12-31T23:59:59Z'
  responses:
    NoContentSuccess:
      description: >-
        No content. The request was successfully executed on the server but
        there is no data to return.
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    AuthenticationError:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    NoAccessError:
      description: >-
        Authentication succeeded, but the user does not have access to the
        resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    NotFoundError:
      description: The resource cannot be found, client-side error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    RateLimitExceededError:
      description: Surpassed the max number of request units for the current hour.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    UnexpectedError:
      description: Unexpected error. Consumer may try to send the request again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
