> ## 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. # Create a Session Token > Exchange your organization Developer Key (Melody Key) for a short-lived **session token** used to control devices. Send your Developer Key as `Authorization: Bearer `. Optionally restrict the token to specific devices by listing their Device Keys; omit `device_keys` to allow every device linked to your organization. The returned token is then used on every `/device/*` request as `Authorization: Bearer ` together with the `X-Device-Key` header. ## Flow 1. Obtain your Organization ID and Developer Key from Melody (see Authentication). 2. Link a device to your organization via `POST /device/otp/confirm/v2` to get its Device Key. 3. Call this endpoint with your Developer Key to receive a session token. 4. Control the device via `/device/*` using the session token and `X-Device-Key`. ## Usage ```bash # 1. Create a session token curl -X POST https://api.getmelody.io/api/sessions/v2 \\ -H "Authorization: Bearer " \\ -H "Content-Type: application/json" \\ -d '{"device_keys": ["alpha-bravo-charlie-delta"]}' # -> { "token": "eyJhbGciOi...", "expires_in": 900 } # 2. Control the device with the session token curl https://api.getmelody.io/device/status \\ -H "Authorization: Bearer " \\ -H "X-Device-Key: alpha-bravo-charlie-delta" ``` ## OpenAPI ````yaml /api-reference/openapi_sdk.yaml post /api/sessions/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 ` and the `X-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: /api/sessions/v2: post: tags: - Authentication summary: Create a Session Token description: > Exchange your organization Developer Key (Melody Key) for a short-lived **session token** used to control devices. Send your Developer Key as `Authorization: Bearer `. Optionally restrict the token to specific devices by listing their Device Keys; omit `device_keys` to allow every device linked to your organization. The returned token is then used on every `/device/*` request as `Authorization: Bearer ` together with the `X-Device-Key` header. ## Flow 1. Obtain your Organization ID and Developer Key from Melody (see Authentication). 2. Link a device to your organization via `POST /device/otp/confirm/v2` to get its Device Key. 3. Call this endpoint with your Developer Key to receive a session token. 4. Control the device via `/device/*` using the session token and `X-Device-Key`. ## Usage ```bash # 1. Create a session token curl -X POST https://api.getmelody.io/api/sessions/v2 \\ -H "Authorization: Bearer " \\ -H "Content-Type: application/json" \\ -d '{"device_keys": ["alpha-bravo-charlie-delta"]}' # -> { "token": "eyJhbGciOi...", "expires_in": 900 } # 2. Control the device with the session token curl https://api.getmelody.io/device/status \\ -H "Authorization: Bearer " \\ -H "X-Device-Key: alpha-bravo-charlie-delta" ``` operationId: post-api-sessions-v2 requestBody: required: false content: application/json: schema: type: object properties: device_keys: type: array description: | Device Keys the session token may control. Omit to allow every device linked to your organization. items: type: string pattern: ^[a-z]+-[a-z]+-[a-z]+-[a-z]+$ example: alpha-bravo-charlie-delta responses: '200': description: Session token created content: application/json: schema: $ref: '#/components/schemas/SessionResponse' '401': description: Missing or invalid Developer Key security: - MelodyKey: [] components: schemas: SessionResponse: type: object description: > Response from POST /api/sessions/v2. Contains a short-lived session token used with the X-Device-Key header. required: - token - expires_in properties: token: type: string description: > JWT session token for device control. Use as `Authorization: Bearer ` with the `X-Device-Key` header. example: eyJhbGciOiJIUzI1NiIs... expires_in: type: integer description: > Token lifetime in seconds. Configurable per organization (default 900 = 15 minutes). example: 900 securitySchemes: MelodyKey: type: http scheme: bearer description: > Developer Key (Melody Key) tied to your organization. Your Organization ID and Developer Key are issued to you by Melody — contact support@getmelody.io to request them. Used to create session tokens via POST /api/sessions/v2, and to link devices via the X-Org-Key header on POST /device/otp/confirm/v2. ````