Skip to main content
NICE CXone Expert
Expert Success Center

Getting Started With the API

Applies to:
All MindTouch Versions
Role required:
Admin
If you are looking to extend the functionality of your site into other systems, this article explains the basics of the CXone Expert API.

Why Do I Need the API?

CXone Expert provides out of the box, easily configurable, integrations in the form of Touchpoints. Touchpoints extend your content into other web applications, CRM's, or websites. However, the Expert API can integrate with applications and systems without a web presentation, such as voice assistants and IoT devices. In addition, integrations with publishing automation systems, user management, and translation management systems can be desirable when CXone Expert becomes a critical piece of your organization's business. 

These types of integrations typically require more complexity and application programming skills. While the API can be easily used to quickly fetch or update content on the fly, it's value is realized when integrations unlock the ability to extend functionality into key parts of an organization.

Do you have further questions? Try consulting the API FAQ.

Technical Details

The API is organized around REST, and is located at the /@api/deki relative URL on an Expert site.

https://example.com/@api/deki

Every resource on the site (pages, users, groups, etc.) is available through the API. Authenticated site users can access the API, through the web browser, once they have signed into the site. System and application integrations require the use of API Tokens to access the API.

HTTPS

API communication is secured with HTTPS. It can be accessed privately and securely by HTTPS compatible clients such as a web browser. The API domain (an Expert site domain) and any additional domains that are required for integrations must be trusted by the HTTPS compatible client or integration. In order to avoid disruptions when SSL/TLS certificates are rotated for these domains, it is highly recommended to trust certificate authority (CA) root and intermediate certificates, as opposed to the domain's server certificate.

In addition to the site domain, integrations with the API rely on HTTPS communication with the following domains:

  • *.cloudfront.net
  • files.mtstatic.com

Responses

The default HTTP response content type is application/xml; charset=utf-8, but an application/json; charset=utf-8 response is possible if API requests include a dream.out.format=json HTTP query parameter.

// XML-encoded response
https://example.com/@api/deki/pages/{id}/info

// JSON-encoded response
https://example.com/@api/deki/pages/{id}/info?dream.out.format=json

Some API endpoints may, by default, respond with a application/json; charset=utf-8 media type or an alternative media type. These defaults are noted in the documentation for those specific API endpoints.

Status Codes

CXone Expert uses conventional HTTP response status codes to indicate the success or failure of an API request. Status codes in the 2xx range indicate successful requests. Status codes in the 4xx range indicate a problem with the request such as a missing URL query parameter or invalid HTTP body format. Status codes in the 5xx range indicate an unexpected, internal problem with the API and can be reported to the CXone Expert Support Team.

On rare occasions, an API endpoint is deprecated and removed. If it is replaced with a new endpoint, under most circumstances, the old endpoint will redirect to the new endpoint. In order for backward compatibility to be maintained, it is important that API clients follow the Location HTTP Header, if a 3xx range status code is returned in an HTTP response.

Name Value Description
OK 200 The request was processed and completed successfully
Accepted 201 The request was accepted successfully and will be processed in a queue
Non-Authoritative Information 203 The request was accepted, however, due to processing errors, the response contains partially complete data 
Moved Permanently 301 The API endpoint was deprecated and replaced with a new location
Found 302 After processing the request, the resource to be returned is located at different URL
Bad Request 400 Invalid or missing request URL query parameter, invalid HTTP body format, or invalid or missing HTTP body parameter value
Unauthorized 401 A request to the authentication API endpoint failed
Forbidden 403 The requested resource is not accessible to due to a permission check or invalid authorization
Not Found 404 The requested resource could not be found
Not Allowed 405 The API endpoint does not support the HTTP method in the request.
Gone 410 The API endpoint was deprecated and was not replaced with a new location

Errors

There are two possible error response formats that can be received from the API. The use of these formats varies between errors and API endpoints, therefore your API integration must be developed to handle both formats. Some response fields have been removed from these examples, as they contain internal metadata that is irrelevant to API integrations.

Default Error Format

<error>
    <exception>{exception}</exception>
    <message>{message}</message>
</error>

Legacy Error Format (Deprecated) 

<error>
    <status>{status}</status>
    <title>{title}</title>
    <message>{message}</message>
    <uri>{uri}</uri>
</error> 
Name Type Description
{exception} string A unique, namespaced key that identifies the error
{message} string The description of the error or explanation of the problem
{status} int The HTTP status code (ex: 400)
{title} string The HTTP status name (ex: Bad Request)
{uri} string The API endpoint URL

Authorization

The API can receive three types of tokens to allow access to site data.

  • All tokens are scoped to and unique to a site
  • Can be a single string value or multiple string values, such as key / secret pairs
  • Token string values can be up to 255 characters long

Auth Token

Auth Tokens (often stylized as authtoken) are set as HTTP cookies in a user's web browser after authentication. Auth Tokens are generated by a site and are cryptographically signed to prevent tampering.

Browser API Token

Browser API Tokens are sent from a website, web application, or simply anything that runs in a web browser to the API. Implementations with Browser API Tokens are written in web browser executable languages such as JavaScript.

Normally, web browsers such as Google Chrome or Mozilla Firefox do not allow JavaScript applications running on one website to access data from another. Browsers block cross-origin requests and responses due to the security issues it can cause, especially if one website's JavaScript application uses the cookies of another website to impersonate a user's identity for nefarious purposes. However, a website can declare which third party websites can securely access its data using Cross Origin Resource Sharing (CORS). Browser API Tokens allow developers to implement CORS in a safe and secure manner. In addition to CORS, Browser API Tokens also allow same origin API access from JavaScript executed in content on a site to the same site's API.

A Browser API Token has no specific user permissions for the API to determine which operations are or are not allowed. User permissions are determined by the web browser session's authtoken HTTP cookie. If the user accessing the integration has not signed in to the site, then the API considers the user to be an anonymous user

Authorizing web browser integrations with the MindTouch API
Authorize integrations between the MindTouch API and websites, web applications, Google Chrome apps, or simply anything that runs in a web browser.
Pages: 2

Server API Token

Server API Tokens are used to create integrations between a server application, IoT, bots, or anything that can communicate over HTTPS, and the API. Implementations with Server API Tokens are typically written in server executed languages such as C#, Java, JavaScript (Node.js), Python, Go, and PHP. The token consists of a key and a secret which are used to sign API requests, allowing valid requests through and rejecting invalid or expired requests. The token secret is meant to be kept in a secure place, and should never be shared or sent across the internet in plain text.

Authorizing server integrations with the MindTouch API
Authorize integrations between the MindTouch API and server applications, IoT devices, bots, or anything that can communicate over HTTPS.
Pages: 2

OAuth API Token

While Server API Tokens provide a developer with the ability to connect applications and devices to the API with unlimited permissions, under some scenarios this level of access control is inappropriate for a developer. Examples include integrations between the API and a third-party service, on behalf of the organization deploying CXone Expert. By implementing OAuth 2.0 authorization flows, OAuth API Tokens allow users to authorize which applications or devices can access their user identities and allowed operations such as reading and writing content. OAuth API Tokens can be safely given to third-party developers, without the concern of handing over site administrator access.

Authorizing OAuth 2.0 integrations with the MindTouch API
Integrate MindTouch users with server applications, IoT devices, bots, or anything that can communicate over HTTPS using an industry-standard authorization framework .
Pages: 2

 

  • Was this article helpful?