Connect a device Beta

Let a user link their device to your agent

Beta. The Device SDK is live for design partners: Dopl issues your project's keys while the developer portal is being built, and @dopl/sdk is available on request. Agents that act for one signed in Dopl user can use the hosted MCP server instead.

1. Create a Connect session

From your server, create a session for the user with the scopes your agent needs. allowed_kinds limits the devices offered, redirect_uri is where the page sends the user when they finish, and branding puts your name, logo and accent color on the page. A publishable pk_ key may also call this route from your app; it is the only route such a key can call.

const session = await dopl.connectSessions.create({
  external_user_id: "usr_123",
  allowed_kinds: ["glasses"],
  requested_scopes: ["present.*", "ask.*"],
  redirect_uri: "https://example.com/connected",
  branding: { display_name: "Acme Agent", accent_color: "#1F6FEB" },
});
{
  "connect_token": "ct_…",
  "url": "https://www.usedopl.com/connect/ct_…",
  "expires_at": "2026-10-27T17:32:11Z"
}

2. Send the user to the page

Open url for the user. They choose a device, pair it, and approve your scopes by risk tier, ticking or unticking each one. The link expires after 30 minutes. When they finish, the page sends them to your redirect_uri with a public_token query parameter, so always pass a redirect_uri.

3. Exchange the token

On your server, exchange the public_token for the connection and its device. A token works once, within 30 minutes; after that, or on a second try, the exchange fails with invalid_request.

const { connection_id, device } = await dopl.connections.exchange({ public_token });
{
  "connection_id": "c3a9e0d4-1f27-4b8e-9d6a-5e8f2c1b7a90",
  "device": {
    "id": "8b0c6f1e-3d2a-4c51-9a7e-2f4d6b1c9e30",
    "kind": "glasses",
    "vendor": "dopl",
    "model": "simulated_glasses",
    "firmware": null,
    "adapter_id": "simulator",
    "adapter_version": "0.1.0",
    "capabilities": [
      {
        "capability": "present.notify",
        "limits": {
          "title_bytes": 64,
          "body_bytes": 480,
          "max_lines": 5
        },
        "latency_class": "interactive",
        "risk_tier": "T1",
        "since_adapter": "simulator@0.1.0"
      }
    ],
    "online": true,
    "last_seen_at": "2026-10-27T17:02:19Z"
  }
}

4. Keep track

List a user's connections, revoked ones included, and revoke one when the user disconnects in your app. Revoking is immediate and safe to repeat.

const { data } = await dopl.connections.list("usr_123");

await dopl.connections.revoke(data[0].id);