Organization access

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. The X-Org-Key header carries this key when you link a device.

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": "orbit-ranch-silver-tomato" }

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": ["orbit-ranch-silver-tomato"]}'

Response:

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

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: orbit-ranch-silver-tomato"

Token summary

Token	Where it comes from	How you send it
Developer 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 last 48 hours by default; expires_in carries the lifetime in seconds. Melody can set a different lifetime for your key, from 1 minute to 7 days. Create a new token when the old one expires.

​Getting access

​Flow

​Token summary

Getting access

Flow

Token summary