Introduction

All API requests to the Voysis query API must supply an authorization token otherwise access to the API will be denied. This chapter will detail Voysis' authorization approach and how tokens are obtained by clients.

Authorization Headers

For both the REST and WebSocket APIs, authorization tokens are supplied in the standard HTTP Authorization header format with a type of Bearer and the value of the token. For the REST API, the header is supplied in the standard HTTP headers of each request. For the WebSocket API, the header is supplied in the headers object of each request message sent over the web socket.

Types of Tokens

Voysis defines two types of tokens that are used.

Session tokens are short-lived tokens, typically being valid for 15 minutes, that are used to authorize API calls. Clients are responsible for maintaining a live application token for the time periods it wishes to make calls to the query APIs. Application tokens are obtained by making a specific API call to the query API using a refresh token.
Refresh tokens are long-lived secret tokens that a client is expected to store in its local state. Refresh tokens are generally valid for the order of weeks or months. The details of how a client obtains a refresh token are specific to each integration with Voysis, though an example scenario is discussed below.

Why Authorization is Required

Authorization of individual clients to the Query API is required to limit the amount of requests that can be made by any single end-user in a given time period. This helps to ensure a consistent experience for all end-users of the API. It is important, therefore, that all tokens:

uniquely identify a single client/end-user (neither refresh nor session tokens should be shared by multiple end-users.)
cannot be forged by external systems.
are hard to "guess" by external systems.
are kept secret both at rest and in transit so that they cannot be intercepted by malicious parties.

If anomalous and detrimental activity is detected from a specific end-user, their refresh tokens can be revoked to prevent them from making further calls to the Query API.

Voysis rate limiting operates a sliding window, allowing a fixed number of API calls per end-user (or per session token) in a time window, typically 15 minutes. The specific limits applied to your end-users can be tweaked by Voysis.

Note that the rate limit on a specific refresh token issuing new session tokens is very low. Client implementations should therefore be careful about caching session tokens for their active lifetime, as once the limit is reached a client will be unable to obtain a new session token until the time window elapses, locking the end-user out of Voice AI functionality.

Obtaining a Session Token

In order to obtain a session token prior to making any Query API calls, a client must make an API call to the /tokens resource providing its current refresh token in the Authorization header. If the refresh token is still valid, a new short-lived session token will be issued to the client which it can then use to make Query API calls. An example request for a new session token looks like this:

curl -X POST \
     -H 'Authorization: Bearer yyqEL28cPBL2Up1wUA3zYxEJghT5BdtsccNbmnqxI5c76IHnJOUpr5b7C0NT8enU' \
     -H 'Content-type: application/json' \
     -H 'Accept: application/json' \
     https://mycompany.voysis.io/tokens

If the given refresh token is valid, the response will contain a JSON structure that contains the session token value and the expiry time of the session token.

{
  "token": "1.eyJpc3N1ZWRCeSI6IjBkZmI4OGMyLTQ2ZTctNGNjZC05YmZiLTQ3OTQ5NTJmN2I5YyIsImlzc3VlZEF0IjoiMjAxOC0wNC0yN1QwODo0NjozOS40NTRaIiwiZXhwaXJlc0F0IjoiMjAxOC0wNC0yN1QwOTowMTozOS40NTRaIiwiZ2VuZXJhdGlvbiI6MSwicGVybWlzc2lvbnMiOlsiY2VyYmVydXM6bGlvbmVsOmFjY2VzcyJdfQ==.53822ae0527256950896a36570797e3122a1b127e7c3ba85d648a7fce9cc36cd45fa829455579ad6c2ad5ec0ebf958d9bb1680a1e1b322357758c1a70e11b2e6",
  "expiresAt": "2018-05-02T09:48:13.000Z"
}

The value of the token property should be used as-is, it is not intended to be interpreted by client applications.

The value of the expiresAt field is a string conforming to the "Internet Date/Time Format" (see section 5.6 of RFC3339), which in turn is a form of datetime defined by ISO8601.

Where a refresh token is invalid (or perhaps expired), the response to a session token request will be 403 Forbidden.

Obtaining a Refresh Token

The way in which a client obtains a refresh token is specific to each customer integration with Voysis. What follows is an example of how a notional customer might integrate their service offering with Voysis in order to issue refresh tokens to their end-users.

In this example, Acme Inc. is integrating Voysis Voice AI into their mobile shopping app. Acme already has a user authentication service that their app talks to, allowing end-users to sign in and interact with their shopping experience. Acme will need to enhance their authentication service to speak directly to Voysis' token issuance service at end-user login. Voysis will issue Acme with an organisation-level refresh token which allows them to issue end-user refresh tokens by making an API call to Voysis. Note that this API call is all on the server-side, it does not involve the end-user or the Acme app directly. Once issued, Acme's authentication service returns the new refresh token back to their app, which can then use the refresh token to obtain a session token.

The general flow is:

The end-user logs in on Acme's app.
Acme's app makes a login API call to Acme's authentication service.
Acme's authentication service makes an API call to Voysis' token issuer requesting a new refresh token.
Acme's authentication service returns the new refresh token to the app.
The app saves the refresh token in its persistent state.
The app makes a call to the /tokens endpoint in the Voysis Query API to obtain a session token.
The app can now make Query API calls for the lifetime of the session token.

Anonymous Access

It is likely that not every customer will want to require end-user login prior to being able to experience Voice AI functionality in their site or app. The structure of the authorization framework does not specifically require an end-user login to occur, only that a refresh token is issued to a singly-identifiable end-user, primarily for rate-limiting purposes. The specifics of how to deal with anonymous versus authenticated users will be specific to each customer integration.

Token Issuer Service

The API call to issue a new refresh token from Voysis' issuer service takes the form:

curl -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer yyqEL28cPBL2Up1wUA3zYxEJghT5BdtsccNbmnqxI5c76IHnJOUpr5b7C0NT8enU' \
     -d '{"uid":"239847", "validity":"P30D"}' \
     https://auth.prod.voysis.io/tokens

The value of uid is a customer-specific value that you wish to associate with the persistent token. Voysis does not interpret this value, it is simply stored alongside the refresh token. This value can be used by Voysis to invalidate any tokens associated with a given UID based on a direct request from you.
- You should never provide sensitive or personally identifiable information in the uid field. As an example, never provide a user's email address, instead provide a one-way hash of the email address.
validity is an ISO-8601 compatible string representing a period (in this example, 30 days). This property can be omitted to use the default value. Note that your account will have an upper limit on refresh token validity and any attempt to assign a longer validity period will result in an error.

On success, the response will be a structure containing the details of the allocated refresh token:

{
  "value": "i9eur29ruFVNVEWK939v73jjekf33uvmoeiHidD8D3mcivv439cnwekjjv42avp0",
  "expiresAt": "2018-05-31T23:21:16.000Z"
}

On failure, the response body will be empty and the HTTP response code will indicate the reason for failure.

Organisation Tokens

The token used to authenticate refresh token requests to the token issuer service is an organisation-level token issued to you by Voysis.

You must keep this organisation token secure, it must only ever reside on your secure infrastructure and never be distributed clients.

Revoking an organisation token will typically require revoking all refresh tokens issued by it, forcing all clients to obtain a new refresh token.

Issuing Tokens at Volume

In certain circumstances, it may be possible to replace the server-side API call to Voysis' token issuance service with a local call. This can be discussed as part of your technical integration with Voysis.

Token Management via Voysis SDKs

Voysis offer SDKs in a number of implementation languages to facilitate writing client applications. Each of these SDKs provides session token management internally, from making the API calls necessary to obtain tokens to maintaining current tokens in local state. Applications are typically required to provide a refresh token to the SDK at initialisation time. Once the SDK has a valid refresh token, it can manage the lifecycle of session tokens.