Authentication

Access to the Melody API is scoped to your organization. Every request that controls a device is authenticated with a short-lived session token derived from your organization Developer Key (Melody Key).

Getting access

Your Organization ID and Developer Key are issued to you by Melody. Contact support to request them — organization and key management is handled by the Melody team.

Keep your Developer Key secret and server-side. Never embed it in browser or mobile clients — issue short-lived session tokens instead.

Flow

Link a device to your organization

The device displays a 6-digit OTP. Submit it with your Developer Key in the X-Org-Key header to link the device and receive its Device Key.

curl -X POST "https://api.getmelody.io/device/otp/confirm/v2" \
  -H "X-Org-Key: <DEVELOPER_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"otp": "123456"}'

Response:

{ "device_key": "alpha-bravo-charlie-delta" }

The Device Key is stable — the same device always yields the same key.

Create a session token

Exchange your Developer Key for a short-lived session token. Optionally scope it to specific devices with device_keys; omit the field to allow every device linked to your organization.

curl -X POST "https://api.getmelody.io/api/sessions/v2" \
  -H "Authorization: Bearer <DEVELOPER_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"device_keys": ["alpha-bravo-charlie-delta"]}'

Response:

{ "token": "eyJhbGciOiJIUzI1NiIs...", "expires_in": 900 }

Control the device

Call any /device/* endpoint with the session token and the target Device Key.

curl "https://api.getmelody.io/device/status" \
  -H "Authorization: Bearer <SESSION_TOKEN>" \
  -H "X-Device-Key: alpha-bravo-charlie-delta"

Token summary

Token	Where it comes from	How you send it
Developer Key (Melody Key)	Issued by Melody	`Authorization: Bearer` on `POST /api/sessions/v2`; `X-Org-Key` on `POST /device/otp/confirm/v2`
Session token	`POST /api/sessions/v2`	`Authorization: Bearer` + `X-Device-Key` on every `/device/*` request
Device Key	`POST /device/otp/confirm/v2`	`X-Device-Key` header identifying the target device

Session tokens are short-lived (default 15 minutes, configurable per organization). Create a new one when it expires.

​Authentication

​Getting access

​Flow

​Token summary

Authentication

Getting access

Flow

Token summary