> ## 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.

# Authentication

> Authenticate with your organization Developer Key and control devices using short-lived session tokens.

# 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](mailto:support@getmelody.io) to request them — organization and key management is handled by the Melody team.

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

## Flow

<Steps>
  <Step title="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**.

    ```bash theme={null}
    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:

    ```json theme={null}
    { "device_key": "alpha-bravo-charlie-delta" }
    ```

    The Device Key is stable — the same device always yields the same key.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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:

    ```json theme={null}
    { "token": "eyJhbGciOiJIUzI1NiIs...", "expires_in": 900 }
    ```
  </Step>

  <Step title="Control the device">
    Call any `/device/*` endpoint with the session token and the target Device Key.

    ```bash theme={null}
    curl "https://api.getmelody.io/device/status" \
      -H "Authorization: Bearer <SESSION_TOKEN>" \
      -H "X-Device-Key: alpha-bravo-charlie-delta"
    ```
  </Step>
</Steps>

## 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.