API Security

Shared token

Accessing the Configuration API or the Recording API requires a token. This token is used by the Xuc process but can also be used to access API from custom server processes. This token must remain on the server and should not be leaked as it would allow API access without restrictions.

To define or change it, you can add or update the value of the PLAY_AUTH_TOKEN environment variable defined in the custom.env of all the following docker environment (where applicable):

XiVO:

/etc/docker/xivo/custom.env

MDS:

/etc/docker/mds/custom.env

XiVO CC:

/etc/docker/compose/custom.env

XiVO UC:

/etc/docker/compose/custom.env

Warning

  • Remind that the value, if defined, must be the same across all XiVO components.

  • When the XiVO CC is splitted on separate server, the value must also be defined consistently.

For more information, see also the Components Configuration and Multi-server installation sections.

Unified Communication Credentials

Depending on the authentication mode you will require different kind of informations to access the CTI API. To simplify and unify authentication, API access is based on a custom token that can be used one of the following way, depending of the API you access:

X-Auth-Token Header:

Adding a HTTP header with a valid token

Query string parameter:

Adding a token parameter with a valid token in the query string part of the API url.

The following sections explain how to get a valid token or trade an external token to a CTI API token.

Login based access

You can use any valid user (see Users) with the following properties:

  • CTI Login enabled

  • Login

  • Password

  • Profile set to any valid value

With these informations you can then use the User basic authentication API to get a CTI API token.

Kerberos token

A kerberos ticket is normally obtained automatically by the browser when accessing a resource requiring access privilge. So in most case a simple HTTP call to the Single sign-in (SSO authentication) API will get you a CTI API token.

CAS token

CAS token can be obtained by authenticating on a CAS server for a given service. Once you have a token, you can trade it to a CTI API token using the Authentication with CAS API.

OpenID Token

OpenID token can be obtained by authenticating on an OpenID server for a given client. Once you have a token, you can trade it to a CTI API token using the Authentication with OpenID Connect (OIDC) API.