voice-trunks

Create a SIP session credential

Issues a workspace-scoped SIP digest credential valid for five minutes. The password appears only in this response; create another credential if you lose it. Trunks must allow session credentials to accept it.

The request has no body. Each successful request creates a fresh credential, including retries. Keep retries bounded: creating more than 20 live credentials for the same caller invalidates the oldest. Treat the password as a bearer secret until expires_at.

post/v1/voice/session-credentials

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/voice/session-credentials
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Headers

Idempotency-Keystring

Does not deduplicate this operation. Every successful attempt creates a fresh credential.

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

Credential minted. The password appears only in this response.

usernamestring required

SIP digest username. Always bird. The credential identifies the workspace through realm. The username does not identify the workspace.

passwordstring required

SIP digest password, returned once. Treat it as a bearer secret: until it expires it can place calls billed to this workspace.

realmstring required

SIP digest realm to authenticate against. Workspace-scoped, so a credential minted for one workspace cannot authenticate against another.

expires_atstring date-time required

When the credential stops authenticating, five minutes after creation. Existing calls may continue; use a fresh credential for later authentication.

handshake_tokenstring

Short-lived token required when upgrading the WebSocket connection. The token authorizes the connection only; each call still authenticates with password.

Example response

{
  "username": "bird",
  "password": "8Kx2mQ7pR4tYvB9nL3sW6dF1gH5jC0aZ",
  "realm": "01ARZ3NDEKTSV4RRFFQ69G5FAV.sip.bird.com",
  "expires_at": "2026-07-30T12:05:00Z",
  "handshake_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3ODU0NDMwMzV9.fp1xWxROEmgCafwiJ-ZHbZg9cIdYC-wLGcH-5gIVbco"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.