Voice SDK Authentication via Telephony Credentials

​

Prerequisites

• An active credential based SIP connection

​

Create a Credential

POST /v2/telephony_credentials HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
Content-Length: 75

{
  "connection_id": "1567510696929005999",
  "expires_at": "2024-09-18T00:00:00",
  "name": "contact-center-1",
  "tag": "sandbox"
}

• connection_id is required
• expires_at is recommended for security especially when many are expected to be created
• name and tag are recommended for easy management

​

Propagation Time and Immediate Use

• Prefer creating credentials ahead of time when possible
• If you create credentials on demand, wait about 5 seconds before the first login or registration attempt
• If you cannot wait, retry with short exponential backoff and treat early failures as transient

​

Updating a Credential

PATCH /v2/telephony_credentials/:id HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
Content-Length: 83

{
  "expires_at": "2024-09-11T21:07:00"
}

{
    "errors": {
        "status": "can't update credentials in expired status"
    }
}

​

Revoking a Credential

DELETE /v2/telephony_credentials/:id HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX

​

Managing Credentials

• filter[resource_id] e.g. filter[resource_id]=connection:1567510696929005999. Note that connection: must be prepended to the connection ID.
• filter[status] e.g. filter[status]=expired
• filter[status] e.g. filter[tag]=sandbox

GET /v2/telephony_credentials?filter[status]=expired&filter[tag]=sandbox HTTP/1.1
Host: api.telnyx.com
Authorization: Bearer XXX

​

How Telephony Credentials Should Be Used

• Create a separate telephony credential for each device
• Do not share one telephony credential across concurrent devices
• JWTs minted from the same telephony credential still represent the same SIP identity

​

SDK Authentication

• sip_username which starts with gencred
• sip_password

​

Check SIP Registration Status

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

​

Limits

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

​

Additional Resources

• Telephony Credentials API Reference
• SIP Registration Status API Reference