Sessions

The Server SDK methods that mint tokens for code running outside your backend: account sessions for embedded components, and user sessions for softphones. How each token is used in the browser, and how it's refreshed, is covered in Authentication.

Create a Session

TypeScript

const session = await dialstack.accountSessions.create({
  account: accountId,
  components: {
    call_logs: { enabled: true },
    voicemails: { enabled: true },
  },
});

console.log(session.client_secret); // a JWT: 'eyJhbGciOi...'
console.log(session.expires_at); // '2025-01-15T13:00:00Z', 1 hour after creation

Parameters

Parameter	Type	Required	Description
account	string	Yes	Account ID to scope the session to
components	object	Yes	Component permissions. At least one component must be enabled — a missing, empty, or all-disabled set is rejected.

Response

TypeScript

interface AccountSessionCreateResponse {
  account: string; // the account the session is scoped to
  account_id: string; // the same value
  client_secret: string; // JWT to hand to the browser SDK
  expires_at: string; // ISO 8601 timestamp, 1 hour after creation
}

Create sessions with your secret key, live or sandbox; the session acts on the matching environment. A session token cannot create further sessions.

Component Permissions

Control which embedded components the session can access:

TypeScript

const session = await dialstack.accountSessions.create({
  account: accountId,
  components: {
    call_logs: { enabled: true },
    voicemails: { enabled: true },
  },
});

Available Components

Component	Description
call_logs	Access to call history
voicemails	Access to voicemails
call_history	Access to the call-history component
phone_numbers	Manage the account's phone numbers
phone_number_ordering	Search for and order new phone numbers
dial_plan	View and edit call routing
ring_groups	Manage ring groups
quality	Call-quality summary and worst calls
ai_agent	Configure the AI agent
account_onboarding	The onboarding portal, including reading the subscription agreement and listing the account's portal administrators
agreement_acceptance	Accepting the subscription agreement — see the warning below

:::warning agreement_acceptance is an attestation

This component lets the session bind the account to the DialStack Service Subscription Agreement — a legal commitment by your customer. It is separate from account_onboarding on purpose: a session with onboarding alone can read the agreement and render the accept screen, so someone who may not sign still learns that service is blocked, but the submission is rejected.

DialStack does not decide who may sign, because the person is your user, not ours. You do, by enabling this component. By minting a session with it, you assert that you presented the agreement to someone entitled to accept on that account's behalf. Enable it for that person and leave it off for everyone else. DialStack's own admin portal, for reference, grants it only to the account's owner.

If you render the onboarding portal, pass canAcceptAgreement with the same condition so a non-signer sees an explanation instead of a button that fails.

:::

Restricting Access

TypeScript

// Only allow voicemails
const session = await dialstack.accountSessions.create({
  account: accountId,
  components: {
    call_logs: { enabled: false },
    voicemails: { enabled: true },
  },
});

A component the session doesn't enable shows an error state, and the API rejects the operations it would have called with 403.

User sessions

User sessions authenticate a single user's softphone: the WebRTC signalling connection and the user's own /v1/me operations. See User tokens for the flow.

Create a user session

TypeScript

const { client_secret, expires_at, user, account } = await dialstack.userSessions.create({
  user: userId,
  ttl_seconds: 3600, // optional
});

Parameter	Type	Required	Description
user	string	Yes	The user the token authenticates as
ttl_seconds	number	No	Token lifetime in seconds. Defaults to 86400 (24 hours); max 604800 (7 days).

TypeScript

interface UserSessionCreateResponse {
  user: string;
  account: string;
  client_secret: string; // JWT to hand to the client
  expires_at: string;
}

The user's account is derived from the user, so no dialstackAccount option is needed. There is no refresh call: mint a new session before the old one expires. The WebRTC SDK asks for one through onTokenExpiring; see Token refresh.

Revoke a user's sessions

TypeScript

const { sessions_revoked_at } = await dialstack.users.revokeSessions(userId);

Every user-session token minted for the user before sessions_revoked_at stops working, and the user's active WebRTC connections are torn down. Call it when a user signs out everywhere or is offboarded.

ICE servers

The TURN and STUN credentials a softphone needs come from GET /v1/webrtc/ice-servers, which the client calls with its user token, not your secret key. The Server SDK has no method for it. See WebRTC.

Next Steps

• Authentication - How session and user tokens are used and refreshed
• Setup - Use account sessions with the browser SDK
• WebRTC - Build a softphone with user sessions