> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmelody.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Confirm OTP and Link Device to Organization

> Confirm a one-time password, link device to organization, and receive a Device Key.

**(Recommended)**: This endpoint returns a Device Key (4 BIP39 words) that identifies the device.
The Device Key is deterministic and stable - the same device always generates the same key.

**Requires X-Org-Key header** with a valid Melody Key to link the device to your organization.

Use the Device Key with `/api/sessions/v2` to create a session token for API access.

## Device Key Format
The Device Key consists of 4 BIP39 words separated by dashes:
```
alpha-bravo-charlie-delta
```

## Flow
1. User enters OTP from device display
2. This endpoint validates OTP and links device to your organization
3. Returns the Device Key
4. Create a session with POST /api/sessions/v2 using your Developer Key
5. Use the session token with X-Device-Key header to control the device




## OpenAPI

````yaml /api-reference/openapi_sdk.yaml post /device/otp/confirm/v2
openapi: 3.1.0
info:
  title: Haptics SDK API
  contact:
    name: Haptics API Support
    email: support@getmelody.io
    url: https://docs.getmelody.io/spec
  description: >
    # Introduction


    Welcome to the Haptics Docs API! You can use our API to access Haptics SDK
    endpoints.


    All API requests must contain header `Content-Type: application/json` by
    default. If not explicitly specified otherwise.


    Haptics Prod: [api.getmelody.io](https://api.getmelody.io)


    Haptics Stage:
    [api.haptics.devlikereal.com](https://api.haptics.devlikereal.com)


    # Authentication


    Access is scoped to your **organization**. Your **Organization ID** and
    **Developer Key** (Melody Key) are issued to you by Melody — contact
    [support@getmelody.io](mailto:support@getmelody.io) to request them.


    To call device endpoints:


    1. Link a device to your organization with `POST /device/otp/confirm/v2`
    (send your Developer Key in the `X-Org-Key` header) to obtain its **Device
    Key**.

    2. Exchange your Developer Key for a short-lived **session token** with
    `POST /api/sessions/v2`.

    3. Call any `/device/*` endpoint with `Authorization: Bearer
    <session_token>` and the `X-Device-Key: <device-key>` header.
  version: v4
servers:
  - url: https://api.getmelody.io
    description: Production
  - url: https://api.haptics.devlikereal.com
    description: Staging
security: []
tags:
  - name: Authentication
    description: >
      Obtain and use organization-scoped access tokens. Your Organization ID and
      Developer Key (Melody Key) are issued to you by Melody — contact
      support@getmelody.io to request them.
  - name: Device Information
    description: |
      The Device Information API encompasses two primary functionalities:

      This section includes endpoints that enable you to:

      - Retrieve detailed information about the device.
      - Access information related to the current session.
      - Update device settings efficiently.
      - Set required device mode.
  - name: Haptic Direct Control
    description: >
      Section convers Direct Control mode. User is able to set position & time
      to get the receiver there.
  - name: Haptic Points Stream
    description: >
      Section covers Points Stream mode. Mode for streaming arrays of signal
      with device position & signal time in the original sender’s timescale. The
      stroker movement velocity is calculated on device and is based on time
      difference between signals. At least two signals needed to calculate
      stroker velocity & move the stroker.
  - name: Haptic Script Control
    description: >
      Section covers Script Playback. The script is sent to device by passing
      the link. After script downloaded by device, server controls device with
      start, stop, pause commands.
  - name: Haptic Loop Control
    description: >
      Section covers Loop Playback. Mode for simple up/down stroking without the
      need for data points. It only needs stroker velocity percentage and
      min/max positions for stroking range to create a loop and move according
      provided range.
  - name: One-Time Password
    description: >
      Section covers One-Time Password. The one-time password is valid for 10-15
      minutes, required for device bootstrapping with 3rd party services.
  - name: Maintenance
    description: >
      This section provides APIs dedicated to the upkeep and troubleshooting of
      the device. Key functionalities include:


      - Firmware Updates: APIs to check for, download, and apply firmware
      updates, ensuring the device is running the latest software version with
      improved features and fixes.

      - Debug Information: Access detailed diagnostic data and logs to
      facilitate troubleshooting and performance analysis.

      - Debug Logging: Enable or disable real-time debug log emission from the
      device. When enabled, the device sends unsolicited `DEBUG_LOG` frames
      (frame type `21`) over the WebSocket. Each frame carries a
      `DebugLogMessage` protobuf payload with a single `message` string field.
      Logs are stored server-side per device (up to 1000 entries) and can be
      viewed in the CMS device detail page.
paths:
  /device/otp/confirm/v2:
    post:
      tags:
        - One-Time Password
      summary: Confirm OTP and Link Device to Organization
      description: >
        Confirm a one-time password, link device to organization, and receive a
        Device Key.


        **(Recommended)**: This endpoint returns a Device Key (4 BIP39 words)
        that identifies the device.

        The Device Key is deterministic and stable - the same device always
        generates the same key.


        **Requires X-Org-Key header** with a valid Melody Key to link the device
        to your organization.


        Use the Device Key with `/api/sessions/v2` to create a session token for
        API access.


        ## Device Key Format

        The Device Key consists of 4 BIP39 words separated by dashes:

        ```

        alpha-bravo-charlie-delta

        ```


        ## Flow

        1. User enters OTP from device display

        2. This endpoint validates OTP and links device to your organization

        3. Returns the Device Key

        4. Create a session with POST /api/sessions/v2 using your Developer Key

        5. Use the session token with X-Device-Key header to control the device
      operationId: post-device-otp-confirm-v2
      parameters:
        - name: X-Org-Key
          in: header
          required: true
          description: Melody Key (Developer Key) that identifies your organization
          schema:
            type: string
            example: MToxMjM0NTY3OC1hYmNkLTEyMzQtNTY3OC1hYmNkZWYxMjM0NTY
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - otp
              properties:
                otp:
                  type: string
                  description: The 6-digit one-time password displayed on the device.
                  example: '123456'
      responses:
        '200':
          description: Device linked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceKeyResponse'
        '400':
          description: Invalid OTP format
        '401':
          description: Missing or invalid X-Org-Key header
        '404':
          description: OTP not found or expired
      security: []
components:
  schemas:
    DeviceKeyResponse:
      type: object
      description: >
        Response containing a Device Key (public device identifier).

        The Device Key is a stable identifier for the device, consisting of 4
        BIP39 words.
      required:
        - device_key
      properties:
        device_key:
          type: string
          description: >
            The Device Key in BIP39 word format.

            Format: 4 words separated by dashes (e.g.,
            "alpha-bravo-charlie-delta").

            This key is deterministic - the same device always produces the same
            key.
          pattern: ^[a-z]+-[a-z]+-[a-z]+-[a-z]+$
          example: alpha-bravo-charlie-delta

````