> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice SDK authentication with telephony credentials

> Authenticate the Telnyx WebRTC Voice SDKs with telephony credentials. Create per-user logins tied to a SIP connection for browser and mobile apps.

# Voice SDK Authentication via Telephony Credentials

## Prerequisites

* An active credential based SIP connection

## Create a Credential

The following API request will create a telephony credential.

```http theme={null}
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

Multiple telephony credentials can be created on a single connection.

## Propagation Time and Immediate Use

Telephony credential creation is not guaranteed to be immediately usable for SDK login or registration. In create-then-login flows, the first authentication attempt can fail transiently even though the API request succeeded.

Best practices:

* 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

After a credential's creation, it may be updated via the PATCH endpoint.

```http theme={null}
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"
}
```

The following error will be returned when trying to perform updates on an `expired` credential since that state is terminal.

```http theme={null}
{
    "errors": {
        "status": "can't update credentials in expired status"
    }
}
```

An expired credential can only be deleted.

## Revoking a Credential

A client-side application’s voice capabilities can be revoked by removing the corresponding credential.

```http theme={null}
DELETE /v2/telephony_credentials/:id HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
```

## Managing Credentials

The following filters are useful when managing many 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`

```http theme={null}
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

A telephony credential is a SIP identity for one SDK device.

Best practices:

* 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

SDKs are authenticated with

* `sip_username` which starts with `gencred`
* `sip_password`

## Check SIP Registration Status

After an SDK client logs in, you can verify whether the underlying telephony credential is currently registered.

```http theme={null}
GET /v2/sip_registration_status?credential_type=telephony_credential&username=gencredabc123 HTTP/1.1
Host: api.telnyx.com
Authorization: Bearer XXX
```

Use the credential's `sip_username` (`gencred...`) as `username`.

## Limits

Currently, there exists

* 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](https://developers.telnyx.com/docs/voice/webrtc/auth/telephony-credentials/index#create-a-credential)
* [SIP Registration Status API Reference](https://developers.telnyx.com/api-reference/uac-connections/sip-registration-status)