{
  "data": {
    "session": {
      "id": "hds_3f9a1c2d4e5b46a7b8c9d0e1f2a3b4c5",
      "deviceSipUsername": "acme-shared-5F-2",
      "userId": "user_2d9kLm7q",
      "deviceLabelSnapshot": "Floor 5 — Desk 2",
      "userDisplayNameSnapshot": null,
      "signedInAt": "2026-09-20T08:30:00.000Z",
      "expiresAt": "2026-09-20T17:00:00.000Z",
      "signedOutAt": null,
      "releaseReason": null,
      "activeForSeconds": 0
    },
    "displaced": [
      {
        "id": "hds_9c8b7a6f5e4d43c2b1a0987654321abc",
        "deviceSipUsername": "acme-shared-5F-2",
        "userId": "user_7Fh2Xs9b",
        "deviceLabelSnapshot": "Floor 5 — Desk 2",
        "userDisplayNameSnapshot": null,
        "signedInAt": "2026-09-20T06:00:00.000Z",
        "expiresAt": null,
        "signedOutAt": "2026-09-20T08:30:00.000Z",
        "releaseReason": "displaced_by_new_session",
        "activeForSeconds": 9000
      }
    ]
  },
  "meta": {
    "request_id": "req_hd_001",
    "timestamp": "2026-09-20T08:30:00.000Z"
  }
}

{
  "data": {
    "session": {
      "id": "hds_3f9a1c2d4e5b46a7b8c9d0e1f2a3b4c5",
      "deviceSipUsername": "acme-shared-5F-2",
      "userId": "user_2d9kLm7q",
      "deviceLabelSnapshot": "Floor 5 — Desk 2",
      "userDisplayNameSnapshot": null,
      "signedInAt": "2026-09-20T08:30:00.000Z",
      "expiresAt": "2026-09-20T17:00:00.000Z",
      "signedOutAt": null,
      "releaseReason": null,
      "activeForSeconds": 0
    },
    "displaced": [
      {
        "id": "hds_9c8b7a6f5e4d43c2b1a0987654321abc",
        "deviceSipUsername": "acme-shared-5F-2",
        "userId": "user_7Fh2Xs9b",
        "deviceLabelSnapshot": "Floor 5 — Desk 2",
        "userDisplayNameSnapshot": null,
        "signedInAt": "2026-09-20T06:00:00.000Z",
        "expiresAt": null,
        "signedOutAt": "2026-09-20T08:30:00.000Z",
        "releaseReason": "displaced_by_new_session",
        "activeForSeconds": 9000
      }
    ]
  },
  "meta": {
    "request_id": "req_hd_001",
    "timestamp": "2026-09-20T08:30:00.000Z"
  }
}

Hot-desking

Hot-desking (also called extension mobility or shared-device login) lets several agents share the same physical desk phone across rotating shifts. When an agent signs in, the phone becomes their extension: inbound calls to their number ring that phone, and outbound calls from it carry their caller ID. When they sign out, the phone returns to the shared pool until the next agent signs in. Retail floors, clinics, manufacturing lines, and hybrid offices typically have more agents than desks. Provisioning one SIP credential per person on a phone nobody owns leaves devices mis-assigned; hot-desking replaces that with a transient user-to-device binding that follows the person.

What hot-desking solves

Shared physical devices — one desk phone serves the morning shift, the evening shift, and a weekend roster without re-provisioning.
Personal call routing on shared hardware — the agent’s extension, caller ID, and queue membership attach to the device for the duration of the session, anywhere they sit.
A clean fallback identity — a signed-out phone keeps its shared-pool SIP credential, so it never dangles without inbound routing. Calls to the pool arrive on the device’s default inbound rule.

Orbit enforces one active session per device and one per user — the same “follow me” semantics as RingCentral Hot Desking or Cisco Extension Mobility.

The agent opens Voice → Hot-desking in the dashboard and enters the device’s SIP username (the shared credential provisioned for that phone), optionally with a friendly label such as Floor 5 — Desk 2.
They can optionally set an end-of-shift time. Orbit signs them out automatically when it passes — treat it as a backstop, not a guarantee.
On sign-in, any prior session involving either party is released atomically: signing in to a phone someone else is using signs them out, and signing in at a second phone signs the agent out of the first.
Signing in to the same phone twice is a no-op — the existing session is re-confirmed rather than duplicated.

What follows the user: their extension, caller ID, voicemail delivery, and queue membership attach to the device for the duration of the session. What stays with the device: its SIP registration, shared-pool inbound rule, and line provisioning. The device never loses its own identity — it only borrows the agent’s. Sign-out is idempotent. Repeating a sign-out does not error; it reports when the session actually ended. An admin can also force-release any active session (terminated employee, lost device) from the same page.

API reference

Five REST endpoints back the dashboard page, mounted at /api/v1/voice/hot-desking. Authenticate with an API key or the dashboard session; sign-in, sign-out, list, and me accept the owner, admin, developer, and agent roles, while the revoke endpoint is restricted to owner and admin. Paths in the SDK samples are relative to /api/v1. POST /api/v1/voice/hot-desking/sign-in binds the calling user to a shared desk phone. Send the phone’s SIP credential username; optionally add a human-readable label and an end-of-shift expiry (ISO-8601, at most 24 hours ahead).

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/hot-desking/sign-in" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "deviceSipUsername": "acme-shared-5F-2",
  "deviceLabelSnapshot": "Floor 5 — Desk 2",
  "expiresAt": "2026-09-20T17:00:00Z"
}'

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! })

// No typed method yet — use the orbit.request escape hatch.
const signedIn = await orbit.request('POST', '/voice/hot-desking/sign-in', {
  deviceSipUsername: 'acme-shared-5F-2',
  deviceLabelSnapshot: 'Floor 5 — Desk 2',
  expiresAt: '2026-09-20T17:00:00Z',
})
console.log(signedIn.data.session.id)
console.log(signedIn.data.displaced?.length ?? 0) // prior sessions released

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

# Same call via the Python SDK's client.request escape hatch.
result = client.request(
    "POST",
    "/voice/hot-desking/sign-in",
    json_body={
        "deviceSipUsername": "acme-shared-5F-2",
        "deviceLabelSnapshot": "Floor 5 — Desk 2",
        "expiresAt": "2026-09-20T17:00:00Z",
    },
)
print(result["data"]["session"]["id"])
print(len(result["data"]["displaced"] or []))

{
  "data": {
    "session": {
      "id": "hds_3f9a1c2d4e5b46a7b8c9d0e1f2a3b4c5",
      "deviceSipUsername": "acme-shared-5F-2",
      "userId": "user_2d9kLm7q",
      "deviceLabelSnapshot": "Floor 5 — Desk 2",
      "userDisplayNameSnapshot": null,
      "signedInAt": "2026-09-20T08:30:00.000Z",
      "expiresAt": "2026-09-20T17:00:00.000Z",
      "signedOutAt": null,
      "releaseReason": null,
      "activeForSeconds": 0
    },
    "displaced": [
      {
        "id": "hds_9c8b7a6f5e4d43c2b1a0987654321abc",
        "deviceSipUsername": "acme-shared-5F-2",
        "userId": "user_7Fh2Xs9b",
        "deviceLabelSnapshot": "Floor 5 — Desk 2",
        "userDisplayNameSnapshot": null,
        "signedInAt": "2026-09-20T06:00:00.000Z",
        "expiresAt": null,
        "signedOutAt": "2026-09-20T08:30:00.000Z",
        "releaseReason": "displaced_by_new_session",
        "activeForSeconds": 9000
      }
    ]
  },
  "meta": {
    "request_id": "req_hd_001",
    "timestamp": "2026-09-20T08:30:00.000Z"
  }
}

The status distinguishes a fresh bind from a re-confirmation: 201 opens a new session, while 200 returns the existing session when you were already signed in to that device — data.displaced is null in that case.

Sign out

POST /api/v1/voice/hot-desking/sign-out releases the caller’s active session and returns the released row. Repeating it returns 410 — never 404 when you had a prior session — carrying when it actually ended and why (data.details.prior).

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/hot-desking/sign-out" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const released = await orbit.request('POST', '/voice/hot-desking/sign-out')
console.log(released.data.signedOutAt) // when the session ended

released = client.request("POST", "/voice/hot-desking/sign-out")
print(released["data"]["signedOutAt"])

{
  "error": {
    "code": "HOT_DESK_ALREADY_SIGNED_OUT",
    "message": "You are already signed out",
    "details": {
      "prior": {
        "id": "hds_3f9a1c2d4e5b46a7b8c9d0e1f2a3b4c5",
        "deviceSipUsername": "acme-shared-5F-2",
        "userId": "user_2d9kLm7q",
        "deviceLabelSnapshot": "Floor 5 — Desk 2",
        "userDisplayNameSnapshot": null,
        "signedInAt": "2026-09-20T08:30:00.000Z",
        "expiresAt": "2026-09-20T17:00:00.000Z",
        "signedOutAt": "2026-09-20T09:45:12.000Z",
        "releaseReason": "user_signed_out",
        "activeForSeconds": 4512
      }
    }
  },
  "meta": {
    "request_id": "req_hd_002",
    "timestamp": "2026-09-20T09:45:13.000Z"
  }
}

List active sessions and check your own

GET /api/v1/voice/hot-desking returns the organization’s active sessions (newest first, capped at 200) — the board behind Voice → Hot-desking. GET /api/v1/voice/hot-desking/me returns only the caller’s active session, or data: null when they are not signed in anywhere.

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/hot-desking" \
  -H "X-API-Key: dv_live_sk_your_key_here"

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/hot-desking/me" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const board = await orbit.request('GET', '/voice/hot-desking')
console.log(board.data.length)               // active sessions

const mine = await orbit.request('GET', '/voice/hot-desking/me')
console.log(mine.data)                       // session object, or null

board = client.request("GET", "/voice/hot-desking")
print(len(board["data"]))                    # active sessions

mine = client.request("GET", "/voice/hot-desking/me")
print(mine["data"])                          # session object, or None

{
  "data": [
    {
      "id": "hds_3f9a1c2d4e5b46a7b8c9d0e1f2a3b4c5",
      "deviceSipUsername": "acme-shared-5F-2",
      "userId": "user_2d9kLm7q",
      "deviceLabelSnapshot": "Floor 5 — Desk 2",
      "userDisplayNameSnapshot": null,
      "signedInAt": "2026-09-20T08:30:00.000Z",
      "expiresAt": "2026-09-20T17:00:00.000Z",
      "signedOutAt": null,
      "releaseReason": null,
      "activeForSeconds": 3610
    }
  ],
  "meta": {
    "request_id": "req_hd_003",
    "timestamp": "2026-09-20T09:30:10.000Z"
  }
}

Force-release a session (admin)

POST /api/v1/voice/hot-desking/:id/revoke force-releases any active session in the organization — the API behind the revoke action on the dashboard. Owner or admin role required. Repeating it returns 410 with the same details.prior shape as sign-out.

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/hot-desking/hds_3f9a1c2d4e5b46a7b8c9d0e1f2a3b4c5/revoke" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const revoked = await orbit.request(
  'POST',
  '/voice/hot-desking/hds_3f9a1c2d4e5b46a7b8c9d0e1f2a3b4c5/revoke',
)
console.log(revoked.data.releaseReason) // 'admin_revoked'

revoked = client.request(
    "POST",
    "/voice/hot-desking/hds_3f9a1c2d4e5b46a7b8c9d0e1f2a3b4c5/revoke",
)
print(revoked["data"]["releaseReason"])  # 'admin_revoked'

Error shapes

Errors return the standard envelope with a details object where the endpoint has context to share. Branch on the status code.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid sign-in body",
    "details": {
      "issues": [
        {
          "field": "deviceSipUsername",
          "message": "deviceSipUsername must be [a-zA-Z0-9._-]{3,128}"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_hd_004",
    "timestamp": "2026-09-20T09:31:00.000Z"
  }
}

{
  "error": {
    "code": "HOT_DESK_RACE",
    "message": "A concurrent sign-in beat this one. Retry to take the device."
  },
  "meta": {
    "request_id": "req_hd_005",
    "timestamp": "2026-09-20T09:31:01.000Z"
  }
}

{
  "error": {
    "code": "HOT_DESK_ALREADY_SIGNED_OUT",
    "message": "You are already signed out",
    "details": {
      "prior": {
        "id": "hds_3f9a1c2d4e5b46a7b8c9d0e1f2a3b4c5",
        "deviceSipUsername": "acme-shared-5F-2",
        "userId": "user_2d9kLm7q",
        "deviceLabelSnapshot": "Floor 5 — Desk 2",
        "userDisplayNameSnapshot": null,
        "signedInAt": "2026-09-20T08:30:00.000Z",
        "expiresAt": "2026-09-20T17:00:00.000Z",
        "signedOutAt": "2026-09-20T09:45:12.000Z",
        "releaseReason": "user_signed_out",
        "activeForSeconds": 4512
      }
    }
  },
  "meta": {
    "request_id": "req_hd_006",
    "timestamp": "2026-09-20T09:45:13.000Z"
  }
}

Status	Code	Meaning
400	`VALIDATION_ERROR`	The sign-in body or revoke path id failed validation; `details.issues` lists each failing field.
404	`HOT_DESK_NO_ACTIVE_SESSION` / `HOT_DESK_NOT_FOUND`	Sign-out or revoke with a caller (or session id) that was never bound.
409	`HOT_DESK_RACE`	A concurrent sign-in won the device/user bind between the check and the write — retry and you take the device.
409	`HOT_DESK_RESERVED`	The desk has an advance reservation held by another user this window; retry after it passes.
410	`HOT_DESK_ALREADY_SIGNED_OUT` / `HOT_DESK_ALREADY_RELEASED`	Repeat sign-out or revoke; `details.prior` carries when the session ended and why.

Configure a hot-desk device

Provision a shared SIP credential for the phone (for example acme-shared-5F-2) under Voice → SIP credentials. This is the pool identity the phone holds while signed out.
Register the device on that credential and confirm it appears as registered.
Label the phone physically with its SIP username so agents can type it at sign-in without guessing.
Agents sign in from Voice → Hot-desking. Admins see every active session there, with signed-in duration and a revoke action per row.

No per-device enablement flag is needed — any registered shared credential can host a session.

Desk reservations are a related but separate feature: a reserved window blocks double-booking, and signing in during your window claims the desk automatically. No-show bookings release themselves.

How sign-out interacts with queues, wallboards, and emergency calling

Queue membership. Signing out releases the user-to-device binding; it does not alter the agent’s queue assignments. If no other device is bound to that agent, inbound queue calls to them find no registered endpoint and fall through to the queue’s no-answer path (next agent, voicemail, or overflow) exactly as with any offline agent. See Voice call lifecycle for how those fallbacks resolve. Wallboards and SLOs. A signed-out, unassigned device contributes no agent presence. Agents-away metrics treat it like any offline endpoint — the device itself is not counted as an idle agent. Emergency calling. Orbit does not route emergency calls, and hot-desking does not change that: a call to 911 / 112 / 999 / 000 from a hot-desk device is rejected pre-flight regardless of who is signed in. Because the binding is transient, the physical location of the phone at call time cannot be assumed from the signed-in user. Post the limitation at the shared desk and point agents to a mobile or landline phone for emergencies. Full detail: Emergency calling.

Session rules

One session per user, one per device. A new sign-in displaces the overlapping prior session — there is never a concurrent double-bind.
Optional auto-sign-out. Set an end-of-shift expiry at sign-in (up to 24 hours ahead). When it passes, the session releases itself and the device returns to the shared pool.
Housekeeping. Sessions record the sign-in IP, time, and a release reason (signed_out, displaced_by_new_session, revoked, or expiry), and every transition lands in the audit log with the actor, device, and timestamps — enough to reconstruct who sat where, when.
Concurrent sign-in races are safe: if two sign-ins collide for the same device or user, one wins and the other is asked to retry.

Troubleshooting

Stuck session — an agent left without signing out, or a session that must end now: open Voice → Hot-desking, find the active session, and use the admin revoke action. The device returns to the shared pool immediately. If the agent sets an end-of-shift expiry at sign-in, stuck sessions clear themselves. “A concurrent sign-in beat this one” — two people signed in to the same device (or the same user signed in elsewhere) at the same moment. Retry; whoever signs in last holds the device. Sign-out says the session already ended — sign-out is idempotent; the response tells you when it actually ended. Check the release reason to see whether the agent signed out, was displaced by a newer sign-in, hit their expiry, or was revoked by an admin. Device not registered — the shared SIP credential must be registered before it can host a session. Re-check the device’s registration under Voice → SIP credentials and see SIP trunk troubleshooting. Inbound calls do not follow the agent — confirm the session is active on Voice → Hot-desking and that the agent’s own extension routes to “current signed-in device.” While no session is active, calls fall to the shared pool’s default inbound rule.

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

Hot-desking (shared-device sign-in)

Hot-desking

What hot-desking solves

API reference

Sign out

List active sessions and check your own

Force-release a session (admin)

Error shapes

Configure a hot-desk device

How sign-out interacts with queues, wallboards, and emergency calling

Session rules

Troubleshooting

​Hot-desking

​What hot-desking solves

​Sign in / sign out workflow

​API reference

​Sign in

​Sign out

​List active sessions and check your own

​Force-release a session (admin)

​Error shapes

​Configure a hot-desk device

​How sign-out interacts with queues, wallboards, and emergency calling

​Session rules

​Troubleshooting

​Related references

Hot-desking

What hot-desking solves

Sign in / sign out workflow

API reference

Sign in

Sign out

List active sessions and check your own

Force-release a session (admin)

Error shapes

Configure a hot-desk device

How sign-out interacts with queues, wallboards, and emergency calling

Session rules

Troubleshooting

Related references