Sip Registrar

Setup Your Dashboard Account For Registrar#

This guide walks through the initial setup for Bandwidth's Registrar. The Registrar allows you to use Bandwidth to create phone calls to and from our network using registered devices.

Pre-Reqs#

Bandwidth Dashboard Account
Registrar activated: contact sales

Create New Realm#

Using the UI#

Select Sip Credentials from the account overview page on the Bandwidth Dashboard

In order to route the calls through Bandwidth, you'll need to create a new realm. Upon realm creation, it will be used as part of the Realm combined with <randomAccountHex>.auth.bandwidth.com.

Value	Required	Description
`Realm`	required	String identifying the realm.
`Description`	optional	A string used for a description of the realm

Create New Sip Credentials#

In order to route the outbound calls through Bandwidth, you'll need to create a new set of SIP credentials. To generate your own hash values, you can skip ahead to the Using the API section of this guide.

Value	Required	Description
`Username`	required	String identifying the user.
`Domain`	optional	String defining the identity of the user. The Domain will be joined to the UserName with an @ to create a composite username. For example, the UserName bob could be combined with the domain somewhere.com to create a composite username bob@somewhere.com
`Realm`	optional	String identifying the realm the user belongs. If left blank/empty the default realm on the account will be used.
`HttpVoiceV2AppId`	optional	String identifying the V2 Voice application to route the call to.
`Hash1`	required	String representing a potential Hash values used to authenticate the client. The value should be computed from an MD5 Hash of: {composite-username}:{Realm}:{Password}.
`Hash2`	required	String representing a potential Hash value used to authenticate the client. The value should be computed from an MD5 Hash of {composite-username}:{Realm}:{Realm}:{Password}.

Select + ADD to add a Sip Credential

Enter a Username, Password and Realm for the Sip Credential

The Sip Credentials and Realms will be displayed here

Using the API#

Generate MD5 Hash#

Either using the command line or an online tool generate the md5 hash from the username and desired password.

Most *nix (mac, linux) come with MD5 hash built in. Check that MD5 is installed by opening up the terminal and typing: Check that MD5 is installed

$ which md5
/sbin/md5

Once MD5 is installed, run the command: md5 -s {composite-username}:{Realm}:{Password} where {Password} is the desired password

Default Setup (No Domain Specified as Part of the User's ID)#

Generate MD5 `Hash1` without Domain#

composite-username	:	realm	:	password
`sipauthtest`	:	`realmname.<randomAccountHex>.auth.bandwidth.com`	:	`password`

md5 -s sipauthtest:realmname.<randomAccountHex>.auth.bandwidth.com:password
MD5 ("sipauthtest:realmname.<randomAccountHex>.auth.bandwidth.com:password") = 93152819b63a1dc050665e544e015eec

Generate MD5 `Hash2` without Domain#

composite-username	@	realm	realm	:	password
`sipauthtest`	@	`realmname.<randomAccountHex>.auth.bandwidth.com`	`realmname.<randomAccountHex>.auth.bandwidth.com`	:	`password`

md5 -s sipauthtest@realmname.<randomAccountHex>.auth.bandwidth.com:realmname.<randomAccountHex>.auth.bandwidth.com:password
MD5 ("sipauthtest@realmname.<randomAccountHex>.auth.bandwidth.com:realmname.<randomAccountHex>.auth.bandwidth.com:password") = 79bb0e55551e14a2f329a282c7cf145

Non-Default Setup (Domain Specified)#

Generate md5 Hash1 with domain `somewhere.com`#

composite-username	:	realm	:	password
`bob@somewhere.com`	:	`realmname.<randomAccountHex>.auth.bandwidth.com`	:	`password`

md5 -s bob@somewhere.com:realmname.<randomAccountHex>.auth.bandwidth.com:password
MD5 ("bob@somewhere.com:realmname.<randomAccountHex>.auth.bandwidth.com:password") = 817d76e91aad032a8c272229f468bfb2

Generate md5 Hash2 with domain `somewhere.com`#

composite-username	@	realm	realm	:	password
`bob@somewhere.com`	@	`realmname.<randomAccountHex>.auth.bandwidth.com`	`realmname.<randomAccountHex>.auth.bandwidth.com`	:	`password`

md5 -s bob@somewhere.com@realmname.<randomAccountHex>.auth.bandwidth.com:realmname.<randomAccountHex>.auth.bandwidth.com:password
MD5 ("bob@somewhere.com@realmname.<randomAccountHex>.auth.bandwidth.com:realmname.<randomAccountHex>.auth.bandwidth.com:password") = 39679d2a73c2e1ea719621bc0d8fdac8

Add the Newly Created Hash to Sip Credentials#

After generating the hash value, fill in the Hash1 and Hash2 values to create the SIP credentials. When using the API, Bandwidth will not generate the hashes for you - you must supply your own hash values. You can create multiple SIP credentials within one API call.

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/sipCredentials
HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<SipCredentials>
    <SipCredential>
        <UserName>sipauthtest</UserName>
        <Hash1>93152819b63a1dc050665e544e015eec</Hash1>
        <Hash1b>c3381b140fbb5e6d7c3ecab774155b6e</Hash1b>
    </SipCredential>
    <SipCredential>
        <UserName>bob</UserName>
        <Domain>somewhere.com</Domain>
        <Realm>realmname.<randomAccountHex>.auth.bandwidth.com<Realm>
        <Hash1>817d76e91aad032a8c272229f468bfb2</Hash1>
        <Hash1b>39679d2a73c2e1ea719621bc0d8fdac8</Hash1b>
    </SipCredential>
</SipCredentials>

Register Device#

After the realm and associated Sip Credential has been provisioned within the Bandwidth Dashboard, input that information into a registered device to begin sending registrations and place SIP calls.

Create Call Using Voice API#

To create a call using Sip Authentication format:

TO field like sip:sipauthtest@realmname.<randomAccountHex>.auth.bandwidth.com
SipAuthUsername as the username created above like sipauthtest
SipAuthPassword as the password used to create the MD5 hash like password

Format the `TO` Field to use Sip Authentication#

sip:+sipauthtest@realmname.<randomAccountHex>.auth.bandwidth.com