User Authentication

VoiceLayer Users

Users who register via VoiceLayer or are created in the admin portal will use the email address and password that they signed up with to log in.

If you wish to use your own server for authentication, VoiceLayer provides additional functionality to allow this.

External Users

In order to allow your own users to authenticate with VoiceLayer, the VoiceLayer platform will need a unique id for each user you wish to authenticate. This can be anything, a number, UUID, email address, username, etc. This identifier is provided to VoiceLayer by your server.

Setup

You will need to create a new API key pair for you authentication server. The authentication server is a server that you own that will be used to log in your own users. It is important that the key type is set to "Server" - you can choose this option from the dropdown when creating an API key.

Integration

There are two API calls required to perform an authentication with one of your users. First you must obtain a nonce from VoiceLayer. This tells VoiceLayer that you are about to authenticate a user.

For this example, we will use the app key abcdefghijklmnopqrstuvwxyz123456 and the app secret nopqrstuvwxyzabcdefghijklm123456

First of all you need to authenticate the user for your system. How you do this is up to you. If the authentication is successful based on the validation of your authentication server, continue to authenticate with VoiceLayer, otherwise display an error to your user.

POST /v1/users/auth/nonce

//token claims
{
  "iat": 1437068430,                        // Current timestamp
  "jti": "some_random_string",              // This is a random string that you should generate
  "iss": "abcdefghijklmnopqrstuvwxyz123456" // API Key
}

This should be signed with the secret to generate a JWT.

//jwt 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0MzcwNjg0MzAsImp0aSI6InNvbWVfcmFuZG9tX3N0cmluZyIsImlzcyI6ImFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MTIzNDU2In0.9ijTs-Ra2bm0Gcx9sGhrPgnySrLzvIL9oaWDvCxRsQ8

This function will return the following JSON if successful:

{
  "nonce": "314c9e472b1c09e7f3f64931057ee0e1"
}

Please note that this nonce will be different from the one you receive. It is randomly generated each time.

Once the nonce has been obtained, the token for the user can be generated by logging them in:

POST /v1/users/auth/token

//token claims
{
  "iat": 1437068435,                           // Current timestamp
  "jti": "314c9e472b1c09e7f3f64931057ee0e1", // nonce returned from previous call
  "iss": "abcdefghijklmnopqrstuvwxyz123456",   // API Key
  "sub": "exampleuser",                        // identifier for the user in your system
}

//jwt
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0MzcwNjg0MzUsIm5vbmNlIjoiMzE0YzllNDcyYjFjMDllN2YzZjY0OTMxMDU3ZWUwZTEiLCJpc3MiOiJhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejEyMzQ1NiIsInN1YiI6ImV4YW1wbGV1c2VyIn0.7xHyT4TA6blYbxKct9M5ZqYWCfMFXU2Q4nr8yqyBN64

Additional properties can optionally be passed in the POST body (for example name). These will be stored along side the user. This call will return JSON in the following format:

{
  "id": "..."
  ...
  "token": "abc3891282vac927ca8c9396c14afeb1",
}

At this point you can use store the token and use it like you would when logging in with a VoiceLayer user for all subsequent API Calls.