Voice SDK Authentication via JWTs

Authenticate the Telnyx Voice WebRTC SDKs with short-lived login tokens. Mint them on your server with the Telnyx SDKs from a credential’s token_material, or request them from the API.

A login token is a JWT that authenticates one telephony credential with the Telnyx WebRTC SDKs. Your backend creates it and hands it to the client, which passes it to the SDK as login_token. The API key and the credential’s secrets never leave your server.

There are two ways to create a login token:

• Mint it on your server with the Telnyx Ruby SDK (TelephonyCredential#to_jwt, telnyx 3.1.0 or later). No request to Telnyx per token: you sign it with the credential’s token_material, which the API returned when the credential was created. Support in the other Telnyx SDKs follows.
• Ask the API for one with POST /v2/telephony_credentials/{id}/token. One request per token.

Both produce a token the SDKs use the same way.

Prerequisites

• A credential connection
• A Telnyx API key, created in Mission Control. Keep it on your server.

Anatomy of a token you mint

A login token is a signed JWT: a header, a payload of claims, and a signature, each base64url-encoded and joined with dots. This is the shape of a token minted on your server; the SDK builds it for you, and the tables are here so you know what the token carries.

A token minted by the API (POST /v2/telephony_credentials/{id}/token) has a different shape: it is signed with HS512, carries aud and iss claims, and has no cty or kid. Treat it as an opaque string; only its 24-hour lifetime matters to your application.

Header

Field	Value
typ	JWT
alg	HS256
cty	telnyx-webrtc;v=1, which marks a token minted on your server
kid	Which Telnyx signing key the credential’s token_material was derived with (v1 today)

Payload

Claim	Meaning
sub	The telephony credential id the token is for
user_id	The Telnyx user that owns the credential
identity	The credential’s sip_username (gencred...). Every token for a credential shares it; a token does not create a new SIP identity
cred_exp	The credential’s expires_at, or null
tel_token	An opaque value Telnyx uses to resolve the credential. Treat it as part of the token, not as data for your application
iat, nbf, exp	Issued at, not before, and expiry, as Unix timestamps
jti	A unique id for the token

Signature

HMAC-SHA256 over header.payload with the credential’s signing_secret from token_material. Telnyx verifies it on login.

Create a login token

Step 1: Create a credential connection

A credential connection is the SIP connection that the telephony credentials, and so the WebRTC clients, belong to. See credential connections.

Step 2: Create an API key

Create an API key in Mission Control. It authenticates your backend to the Telnyx API. It is only ever used on the server.

Step 3: Create a telephony credential and keep its token_material

Create one telephony credential per user or device (see telephony credentials for the full request). The response carries the credential’s id, its SIP credentials, and token_material:

{
  "data": {
    "id": "c215ade3-0d39-418e-94be-c5f780760199",
    "record_type": "credential",
    "resource_id": "connection:1567510696929005999",
    "user_id": "a62d8f27-0f6c-4a3c-8c5a-3e8b4c2f1d90",
    "sip_username": "gencrednCvHU5IYpSBPPsXI2iQsDX",
    "sip_password": "a92dbcfb60184a8cb330b0acb2f7617b",
    "expires_at": null,
    "token_material": {
      "kid": "v1",
      "tel_token": "rj_ZkkZUOZMxZOfOmLpEUB3siU7u6RjZFeM9s-gb_xCR56WFKFAJiMyF2T6CBRmlh_Sy0i_lfyT9AI8sEif8MTIIszyzSl_aDnG48aO50yaHGuRSYbUbSYm9WIiQ0g==",
      "signing_secret": "cCL985ACi7wpbe_2xh1VDF3NabPJ90u1wCKmJCPNpxw"
    }
  }
}

Store the credential’s id, user_id, sip_username, expires_at and token_material with the user they belong to. With them your server can mint login tokens for as long as the credential lives, with no further requests.

token_material is as sensitive as sip_password: together they let anyone place calls as that credential. Keep it on your server, never send it to a browser or mobile app, and never log it.

If you did not keep the material, fetch it again for any existing, non-expired credential you own:

GET /v2/telephony_credentials/{id}/token_material HTTP/1.1
Host: api.telnyx.com
Authorization: Bearer XXX

Step 4: Mint a login token on your server

Use the Telnyx Ruby SDK (gem "telnyx", "~> 3.1") on your backend. For a credential object returned by create, to_jwt signs the token locally from the token_material it already carries. For a credential you retrieved, or built from stored values, pass the material in or let the SDK fetch it once.

Ruby

# telnyx >= 3.1.0
require "telnyx"
Telnyx.api_key = ENV.fetch("TELNYX_API_KEY")

# Once, when the user is set up: create the credential and keep what to_jwt needs.
credential = Telnyx::TelephonyCredential.create(connection_id: ENV.fetch("TELNYX_CONNECTION_ID"))
store_for_user(user_id,
  credential_id: credential.id, user_id: credential.user_id, sip_username: credential.sip_username,
  expires_at: credential.expires_at, token_material: credential.token_material.to_h)

# On every login: no request to Telnyx.
login_token = credential.to_jwt(ttl: 3600)

# Or from the stored values, without a TelephonyCredential object:
stored = load_for_user(user_id)
login_token = Telnyx::AccessToken.new(
  credential_id: stored[:credential_id], user_id: stored[:user_id], identity: stored[:sip_username],
  expires_at: stored[:expires_at], token_material: stored[:token_material], ttl: 3600
).to_jwt

ttl is the token lifetime in seconds, from 1 to 86400 (24 hours). The default is one hour. Mint tokens for the shortest lifetime that works for your application, and mint a new one for each login.

Or ask the API for a token

If you prefer not to hold token_material, request a token per login. Telnyx signs it; it is valid for 24 hours.

POST /v2/telephony_credentials/{id}/token HTTP/1.1
Host: api.telnyx.com
Authorization: Bearer XXX

The response body is the token as plain text.

Step 5: Authenticate the SDK

Send the token to your client over your own authenticated channel and pass it to the SDK as login_token:

const client = new TelnyxRTC({ login_token: loginToken });
client.connect();

Refresh before expiry: the JS SDK fires TOKEN_EXPIRING_SOON and accepts a new token through client.updateToken(newToken) without reconnecting. See authenticating your app for the JS SDK flow; the mobile SDKs take the same login_token.

Token lifetime

A login token stops working at the earliest of:

• its exp (the ttl you chose, or 24 hours for an API-minted token)
• the expiry of its telephony credential (expires_at)
• the deletion of its telephony credential

To revoke a user’s access, delete or expire the credential. Tokens have no revocation of their own, so keep lifetimes short.

What a login token represents

A login token authenticates one telephony credential. It does not create a new SIP identity.

Best practices:

• Tokens minted from the same telephony credential all represent the same sip_username (gencred...)
• Create a separate telephony credential per device, then mint tokens from that credential

Immediate login after credential creation

If you create a telephony credential and log in with a token for it right away, wait about 5 seconds first. Using the credential immediately after creation can fail transiently while it propagates. Retry with a short backoff and treat early failures as transient.

Check SIP registration status

If you need to confirm whether the SDK is currently registered, use the underlying telephony credential’s sip_username (gencred...) with the SIP Registration Status endpoint.

GET /v2/sip_registration_status?credential_type=telephony_credential&username=gencredabc123 HTTP/1.1
Host: api.telnyx.com
Authorization: Bearer XXX

Limits

Currently, there exists

• No limit on count of tokens on a telephony credential,
• Nor any limit on the aggregate count of tokens on a single account.

Additional resources

• Create an Access Token API reference
• Retrieve token material API reference
• SIP Registration Status API reference