AUTHENTICATION

Session tokens

Session tokens are short-lived credentials minted by Phonic on your behalf. They let client-side code authenticate to Phonic without ever seeing your PHONIC_API_KEY.

Use session tokens when your code runs in a browser, mobile app, or any environment you do not fully control. Use an API key directly when your code runs on your own backend.

How it works

  1. Your backend calls POST /v1/auth/session_token using your API key.
  2. Phonic returns a token of the form ph_session_... with a TTL you choose.
  3. Your client uses that token to open a conversation WebSocket.
  4. The token expires automatically. To extend a session, mint a new one.

1. Mint a session token

The endpoint accepts a ttl_seconds field between 60 and 3600. The default is 300 (five minutes).

1import { PhonicClient } from "phonic";
2
3const client = new PhonicClient({
4  apiKey: process.env.PHONIC_API_KEY,
5});
6
7const { session_token, expires_at } = await client.auth.createSessionToken({
8  ttl_seconds: 300,
9});

2. Use the session token

Pass the token as the session_token query parameter when opening the conversation WebSocket:

wss://api.phonic.ai/v1/sts/ws?session_token=ph_session_abc123...

Session tokens cannot be combined with any other authentication mechanism on the same request.

Revocation

Session tokens are stored server-side and can be revoked instantly by Phonic if needed. In practice, however, the simplest revocation strategy is to keep the TTL short and let tokens expire on their own.

If you need stateless verification without a round-trip to Phonic, use JWTs instead.

Choosing a TTL

  • Shorter TTLs reduce the impact of a leaked token, but force clients to refresh more often.
  • Longer TTLs are more convenient, but extend the exposure window if a token leaks.

The default of 300 seconds works for most use cases. If a single user session may include several conversations back-to-back, raise the TTL or have your backend mint a fresh token before each conversation.