---
title: "Voice Token"
method: POST
path: "/telephony/voice-token"
tags: ["telephony"]
---

# Voice Token

`POST /telephony/voice-token`

## Request

- Base URL: `https://api.verdun.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.verdun.ai/telephony/voice-token`
- Auth: HTTP bearer

Mint a short-lived Twilio Voice access token for the browser softphone.

EITHER PERMISSION that can start a browser leg: escalate_dispatch (police)
or notify_property_owner (the property contact). read_only holds neither
and is refused, which is pinned by test.

Widening WHO may hold a token does not widen what can be dialled with one:
the grant is outgoing-only and bound to our TwiML App, and
build_softphone_twiml still enforces the per-row identity, one-shot and
freshness checks before any number is dialled, and re-reads the operator's
permissions against the reservation's target_type — and the reservation's
event against their current tenant scope — at that moment, so a token held
on one permission cannot consume a reservation that needs the other, and a
revoked tenant grant cannot be dialled through. 503 until browser calling
is configured AND the dispatch launch gate is on.

## Response `200`

Successful Response

- VoiceTokenResponse
  - `token` string, required: Twilio Voice access token (JWT) for the browser softphone. The outgoing grant is bound to the server's TwiML App — it cannot dial arbitrary numbers. An incoming grant is added only when incoming_allowed.
  - `identity` string, required: The token's client identity: the operator's UUID in 32-char hex form (Twilio identities allow only alphanumerics and underscores).
  - `ttl_seconds` integer, required: Seconds until the token expires; the SDK's tokenWillExpire event is the refresh hook.
  - `incoming_allowed` boolean: True when this token also carries the incoming grant (INBOUND_CALLS_ENABLED and the caller is central staff with a calling permission). The console registers a Device to receive calls only when this is true.

---

[API](https://skmtc.dev/verdun/apis/verdun-api.md) - [All operations](https://skmtc.dev/verdun/apis/verdun-api/llms.txt) - [OpenAPI document](https://skmtc.dev/verdun/apis/verdun-api/revisions/35a2a6ebedda?raw)