Management API

The Management API allows you to fully integrate all functions within the Syntphony CAI's Cockpit into your own service or system, seamlessly integrating Syntphony CAI's system within your solution.

Audience

The Management API covers 100% of the functions that the cockpit has to offer to manage your virtual agents and their content. The following documentation targets two people:

• Technical teams who intend to either partially or fully integrate the cockpit's functions within your own system

• Technical teams attempting to fully understand the behavior of Syntphony CAI.

While one may find that reintegrating all of Syntphony CAI's cockpit functions pointless, this API offers you the possibility of allowing your team to access specific features from Syntphony CAI without the need of granting them access to Syntphony CAI's cockpit, by accessing them directly from your website with a generic user token.

For instance, you could consume the data used in the Dashboard API to have your Virtual Agent's usage reports exposed on your website, or to enable the training option in a button on your website, in which someone without Syntphony CAI access could use.

How to use this API

Authentication

Authentication must be handled following the OAuth2 Bearer Token protocol, where one must authenticate with a valid, expirable token.

Once obtained, the access token must be sent in your header ‘Authorization’ as the string: “Bearer {{access_token}}” on every request.

While the Conversation API allows you to use either a User Token or Client Credentials, the methods found in this documentation requires you to use User Token.

Obtaining your Authentication Token

To generate a token, make a request on the following endpoint:

POST

{{keycloak_url}}/auth/realms/{{org_name}}/protocol/openid-connect/token

Request Body

client_id: eva-cockpit
username: {{‘[e-mail]’ }}
password: {{‘Password123’}}
grant_type: password

Content-Type is ‘x-www-form-urlencoded’. Username and password are your own credentials; client_id and grant_type are fixed texts. If you lack credentials, ask your administrator to issue a valid user to your environment.

Sample Response Body

While there are several, default fields that you may map from the OAuth2 response body, we recommend you to map those, as they are the only ones you will need to use.

Name	Type	Description
access_token	String	Your bearer token. Can be as long as 800 characters.
expires_in	Integer	Lifetime of your token, in seconds.
refresh_expires_in	Integer	Lifetime of your refresh token, in seconds.
refresh_token	String	Your refresh token, used to renew your token. (See below)

Sample response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJjUkgxUkZSNkswejU1MmFxUTNmR2JOa0NteFg5dEVTelJRdjktclRMWkRVIn0.eyJleHAiOjE2MzE1NjE1MjAsImlhdCI6MTYzMTU2MTIyMCwianRpIjoiZDc4M2ZkYzQtYjEwNC00NmM2LWIxMGItY2JiNjRlYzk4MjIxIiwiaXNzIjoibmFuYW5pbmFuYW8iLCJzdWIiOiI5OTAxNGJiYS1hNDA3LTRjMDgtODExNi0xNzQ2MTVlZDU3OTIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJldmEtY29ja3BpdCIsInNlc3Npb25fc3RhdGUiOiIwOWU0YmMxNi01ODhhLTQzNGItOTVjMy1jNmIyMmMxMzBiMGUiLCJhY3IiOiIxIiwic2NvcGUiOiIifQ.TdIj45LlKktpPpwiuiQEN4-Ri47H2BCHLlBbpMQH_7F6HOwQgJhtLDBRcOQEew14UUZESzK-fTyV0Hwe2aWaT_kkx_xZeM1GPmhACIbz7JlVHL6Y8xu43rMl5DsmlQgj8jiDW4Z9ZvYxNJ0fVG_tjK-5eiuIB-KJd7TSvGU0H8yZ3p8ciFcUAlNQH4ufiaxz_VZqwXI6WVj7DDU5dgdpu8rxkGuTUb4urLO0yfRza1QQCoDhRHODTlO0nJRJC0Dc6N_WLpbJIlXFNnaAEQbnMZ-b8CBcDNUwRJdtDbqLDO9Lrd2FaOU8L1CE3U11_t1uje0fKy9G2T6iqav1HAy5kg",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmZmIyZGU1OC1iNDU3LTRmNmItODI3Yi1hMjUxNGY4YTQ1ZjAifQ.eyJleHAiOjE2MzE1NjMwMjAsImlhdCI6MTYzMTU2MTIyMCwianRpIjoiNGI3MWE4NjYtZjk1YS00MDAxLThjMDEtZDdjODdiOTNhYWNmIiwiaXNzIjoibmFuYW5pbmFuYW8iLCJhdWQiOiJuYW5hbmluYW5hbyIsInN1YiI6Ijk5MDE0YmJhLWE0MDctNGMwOC04MTE2LTE3NDYxNWVkNTc5MiIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJldmEtY29ja3BpdCIsInNlc3Npb25fc3RhdGUiOiIwOWU0YmMxNi01ODhhLTQzNGItOTVjMy1jNmIyMmMxMzBiMGUiLCJzY29wZSI6IiJ9.fBMyJeLsT6JuE9kzQNUGl3FZWvrZ3teA5VgPptXAQlQ",
    "token_type": "Bearer",
    "not-before-policy": 1619470285,
    "session_state": "09e4bc16-588a-434b-95c3-c6b22c130b0e",
    "scope": ""
}

Authentication Token Renewal

Authentication tokens may expire, as indicated by the ‘expires_in’ field from the token generation response. When it does so, you may still renew it without reentering credentials, by calling the same endpoint, but with the following request body:

Renewal Request Body

client_id: eva-cockpit
grant_type: refresh_token
refresh_token: {{The ‘refresh_token’ from the previous response body}}

Once again, Content-Type is ‘x-www-form-urlencoded’. If your refresh_token has also expired (indicated by the field ‘refresh_expires_in’), you are required to generate a new token by reentering the client credentials.

Token Access Restriction

Authentication tokens generated through user/password acceess will reflect whichever configuration you have for the user. You may properly configure your user so that is has restricted access on any given environment or bot. By restricting it's access, you may ensure that the token used for one of your bots has no access to any other Syntphony CAI resource from your organization.

This means that you could either fully integrate a login function on your services that internally log into Syntphony CAI, or have a group of pre-set accounts in which your functions use.

You could, for instance, have a preset Reader-only token with restricted access to some or your users, and another preset user with Admin access for other users with full access.

Endpoints

The API endpoints differ from those you use to log in the Syntphony CAI cockpit.

In order to use this API, we ask that you open a ticket and request access to your Management API base URLs, which will be at least 2, but may be more.

We have a separate Admin base URL, and an individual base URL for each of our instances. Should you have a single instance, there is no need for disambiguation. If you have more than one, the Admin API also has methods to discern which instance you want for each environment.

All of the endpoints on this documentation follow this pattern:

https://{{BASE_URL}}/{{API_SUBPATH}}/{{METHOD_ENDPOINT}}

Field	Value
BASE_URL	The base URL your service refers to. YOu may request this value through a ticket.
API_SUBPATH	The API subpath. Each page here lists a subpath, and all methods found within must use this subpath.
METHOD_ENDPOINT	The method endpoint, found at each request.

So if your BASE_URL is 'my-service-admin.eva.bot', your API_SUBPATH is 'eva-user' and your METHOD_ENDPOINT is '/org/{orgUUID}/users', your final endpoint will look like the following:

https://my-service-admin.eva.bot/eva-user/org/be207f03-925c-4fb9-8b81-43660f70fd95/users

Recommended Practices

While you can learn about Syntphony CAI by reading this documentation, we strongly recommend that any teams attempting to integrate our API into your system actually use the eva-cockpit in a development environment, and familiarize with each used concept.

All Models and APIs are named accordingly to the names seen on the cockpit - the sole exception being "Bots" which are referred to as "Virtual Agents".

Understanding the purpose for each of those elements and their connections by using the cockpit will strongly assist you in identifying what are the relevant integrations to achieve a specific objective, and what can be ignored.

We also recommend you to ensure your traffic is properly cryptographed to ensure you are not exposing keys to your organization and environments. By requesting the access to the Management API, you are declaring you will ensure that traffic data will be properly secured by you.