openapi: 3.0.3
info:
  title: Device keys
  description: >-
    **Device keys** are used to cryptographically bind devices to a user for
    strong device identification. This allows the device to act as a
    user-identifying factor, and allows elevating trust for known devices.
    <br><br> These APIs are used to manage and verify bound devices for a user
    and application. The device may correspond to either a browser (for web
    apps) or a mobile device (for mobile apps).<br><br>Device binding relies on
    a cryptographic key-pair generated by the device. The private key is
    securely stored on the device (typically protected by biometrics or a PIN),
    while the public key is stored by Transmit for a given user. When needed,
    the device uses the private key to sign a challenge that Transmit verifies
    using the public key.<br><br>**Note: This feature requires the client to
    implement the relevant cryptography APIs exposed by the browser or mobile
    platform (Android or iOS).**
  version: ''
servers:
  - url: https://api.sbx.transmitsecurity.io/cis
    description: Sandbox environment
  - url: https://api.transmitsecurity.io/cis
    description: Production environment (US)
  - url: https://api.eu.transmitsecurity.io/cis
    description: Production environment (EU)
  - url: https://api.ca.transmitsecurity.io/cis
    description: Production environment (CA)
  - url: https://api.au.transmitsecurity.io/cis
    description: Production environment (AU)
security: []
paths:
  /v1/users/{user_id}/device-keys:
    post:
      operationId: createDeviceKeys
      summary: Add device key
      description: >-
        Registers a device key in the platform for a specific user and app.
        Device keys are generated by the client using the relevant cryptography
        APIs exposed by the browser or mobile platform (Android or iOS). Once
        registered, the device key cryptographically binds the device to the
        given user for secure device identification. <br><br>**Note:** The key
        should be generated using the RSA-PSS algorithm and SHA-256 hash.
        <br><br>**Required permissions**: `apps:create`, `[appId]:create`,
        `devices:create`.
      parameters:
        - name: user_id
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiDeviceKeyCreationInputDto'
      responses:
        '201':
          description: Device key added
      security:
        - ClientAccessToken: []
    get:
      operationId: getDeviceKeysForUser
      summary: Get all device keys
      description: >-
        Retrieves all the device keys registered for a specific user. This can
        be used to display a list of the user's devices. <br><br>**Required
        permissions**: `apps:read`, `[appId]:read`, `devices:read`, `apps:list`,
        `[appId]:list`, `devices:list`.
      parameters:
        - name: user_id
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getDeviceKeysForUser
                type: object
                required:
                  - result
                description: List of user's devices
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeviceKeyResponseDto'
      security:
        - ClientAccessToken: []
  /v1/users/{user_id}/device-keys/{key_id}:
    get:
      operationId: getDeviceKeys
      summary: Get device key
      description: >-
        Retrieves a specific device key. For example, this can be used to verify
        that the device key exists and is active. <br><br>**Required
        permissions**: `apps:read`, `[appId]:read`, `devices:read`.
      parameters:
        - name: user_id
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
        - name: key_id
          required: true
          in: path
          description: An identifier for the user's device
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getDeviceKeys
                type: object
                required:
                  - result
                description: Device key
                properties:
                  result:
                    $ref: '#/components/schemas/DeviceKeyResponseDto'
      security:
        - ClientAccessToken: []
    put:
      operationId: updateDeviceKey
      summary: Update device key
      description: >-
        Updates the metadata of a device key, such as the friendly device name
        or other custom data. <br><br>**Required permissions**: `apps:edit`,
        `[appId]:edit`, `devices:edit`.
      parameters:
        - name: user_id
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
        - name: key_id
          required: true
          in: path
          description: An identifier for the user's device
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiDeviceKeyUpdateInputDto'
      responses:
        '200':
          description: Device key updated
      security:
        - ClientAccessToken: []
    delete:
      operationId: deleteDeviceKeys
      summary: Delete device key
      description: >-
        Unregisters the user's device. For example, it can be used in case the
        device is lost, stolen, or no longer in the user's possession.
        <br><br>**Required permissions**: `apps:delete`, `[appId]:delete`,
        `devices:delete`.
      parameters:
        - name: user_id
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
        - name: key_id
          required: true
          in: path
          description: An identifier for the user's device
          schema:
            type: string
      responses:
        '204':
          description: Device key deleted
      security:
        - ClientAccessToken: []
  /v1/users/{user_id}/device-keys/{key_id}/validate:
    post:
      operationId: validateDeviceKeys
      summary: Validate device key
      description: >-
        Verifies that the user's device is in their possession. Before calling
        this API, the device signs a challenge using the private key stored by
        the device. This API is used to verify the signed challenge using the
        device public key. In case the device is blocked, this validation will
        fail.<br><br>**Note: The challenge should be generated by your client
        backend.**. <br><br>**Required permissions**: `apps:execute`,
        `[appId]:execute`, `devices:execute`.
      parameters:
        - name: user_id
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
        - name: key_id
          required: true
          in: path
          description: An identifier for the user's device
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiDeviceKeyValidationInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiValidateDeviceKeyResponse'
      security:
        - ClientAccessToken: []
  /v1/users/{user_id}/device-keys/{key_id}/block:
    put:
      operationId: blockDeviceKey
      summary: Block device key
      description: >-
        Block a user's device. Once blocked, the device status will be `Blocked`
        and device validation will fail if requested. <br><br>**Required
        permissions**: `apps:edit`, `[appId]:edit`, `devices:edit`.
      parameters:
        - name: user_id
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
        - name: key_id
          required: true
          in: path
          description: An identifier for the user's device
          schema:
            type: string
      responses:
        '200':
          description: Device blocked
      security:
        - ClientAccessToken: []
  /v1/users/{user_id}/device-keys/{key_id}/unblock:
    put:
      operationId: unblockDeviceKey
      summary: Unblock device key
      description: >-
        Unblocks a user's device. Once unblocked, the device status returns to
        `Active` and the device can be verified using the device key.
        <br><br>**Required permissions**: `apps:edit`, `[appId]:edit`,
        `devices:edit`.
      parameters:
        - name: user_id
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
        - name: key_id
          required: true
          in: path
          description: An identifier for the user's device
          schema:
            type: string
      responses:
        '200':
          description: Device unblocked
      security:
        - ClientAccessToken: []
components:
  schemas:
    ApiDeviceKeyCreationInputDto:
      type: object
      properties:
        key_id:
          type: string
          description: An identifier for the user's device
        display_name:
          type: string
          description: >-
            Friendly device name, used when displaying a list of the user's
            devices
        custom_data:
          type: object
          description: >-
            Custom data stored for this device, such as tags or device data
            obtained using other tools
        push_config:
          description: Device push notification configuration
          allOf:
            - $ref: '#/components/schemas/DevicePushConfigDto'
        public_key:
          type: string
          description: >-
            Device public key as a base-64 string. This corresponds to the
            cryptographic key-pair generated by the client
      required:
        - key_id
        - public_key
    DeviceKeyResponseDto:
      type: object
      properties:
        status:
          description: Status of the device
          $ref: '#/components/schemas/DeviceStatus'
        display_name:
          type: string
          description: >-
            Friendly device name, used when displaying a list of the user's
            devices
        custom_data:
          type: object
          description: >-
            Custom data stored for this device, such as tags or device data
            obtained using other tools
        push_config:
          description: Device push notification configuration
          allOf:
            - $ref: '#/components/schemas/DevicePushConfigDto'
        key_id:
          type: string
          description: Identifier of the user's device
        created_at:
          format: date-time
          type: string
          description: Date the device key was added
        updated_at:
          format: date-time
          type: string
          description: Date the device key metadata was last updated
      required:
        - status
        - created_at
        - updated_at
    ApiDeviceKeyUpdateInputDto:
      type: object
      properties:
        display_name:
          type: string
          description: >-
            Friendly device name, used when displaying a list of the user's
            devices
        custom_data:
          type: object
          description: >-
            Custom data stored for this device, such as tags or device data
            obtained using other tools
        push_config:
          description: Device push notification configuration
          allOf:
            - $ref: '#/components/schemas/DevicePushConfigDto'
    ApiDeviceKeyValidationInput:
      type: object
      properties:
        challenge:
          type: string
          description: Raw challenge before it was signed by the device
        signature:
          type: string
          description: Signed challenge
      required:
        - challenge
        - signature
    ApiValidateDeviceKeyResponse:
      type: object
      properties:
        result:
          type: boolean
          readOnly: true
          description: Boolean value indicating if device key validation succeeded
      required:
        - result
    DeviceStatus:
      type: string
      enum:
        - Active
        - Blocked
        - Suspended
    DevicePushConfigDto:
      type: object
      properties:
        device_token:
          type: string
          description: >-
            Device token for push notifications (FCM registration token or APN
            device token)
          minLength: 32
          maxLength: 255
        type:
          type: string
          enum:
            - FCM
            - APN
          description: Type of push notification
        bundle_id:
          type: string
          description: Bundle identifier, used for push notifications
      required:
        - device_token
        - type
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    UserAccessToken:
      type: http
      description: >-
        A token returned upon end-user authentication, which provides access to
        resources and data for the user and app for which it was generated
      scheme: bearer
      bearerFormat: JWT
    AdminAccessToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes: {}
      description: >-
        A token generated by a management application using the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken). It provides
        access to all resources for the tenant and its apps
    ClientAccessToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes: {}
      description: >-
        A token generated by an end-user application using the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken). It provides
        access to resources and data on the tenant level or associated with the
        specific application (but not other apps in the tenant)
    OrgAdminAccessToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes: {}
      description: >-
        A token returned upon B2B authentication for a user that has the
        organizationAdmin or organizationCreator role.
