MXO API Security

MXO APIs use OAuth 2.0 authentication.

A full description of the OAuth 2.0 standard is available at the following link: The OAuth 2.0 Authorization Framework.

MXO supports the Client Credentials grant type.

Before Using OAuth 2.0 with the MXO APIs

We recommend creating a dedicated user ID for API calls. For example, api-user@my.tenant. Note that the API user can share the same email address as a normal user. This allows you to have better control over access to your Spaces.

Creating API Credentials for a User in MXO

Use the API Credentials page in Interaction Studio create API credentials for users who require access to the APIs.

To access the API credentials page, click Configure > API Credentials in the main Interaction Studio UI.

AS Icon

Use the API Credentials page in MXO Admin Settings to create API credentials for users who require access to the APIs.

To access MXO Admin Settings, click the Admin Settings icon in the main MXO UI.

For more information, see Generate API Credentials for a User.

Note: Only users with the Admin Role can access the API Credentials page and create API credentials for other users.

Request an OAuth 2.0 Token from MXO

You must request a valid OAuth 2.0 token from MXO to use our APIs. Use your preferred API client to make the request, ensuring you provide the following details:

FieldDescription
Token NameName for your new access token.
Access Token URLYour Access token URL. For example: https://<oneservername>.thunderhead.com/one/oauth2token
Grant Typeclient_credentials
Client IDThe client ID generated for you in MXO.
Client SecretThe client secret generated for you in MXO.
Client AuthenticationAccept the default (Basic Auth header).

View Your API Credentials

You can view the API Credentials and Access Token URL required when requesting an OAuth 2.0 Access Token, by clicking Configure API Credentials in the main Interaction Studio UI.

  1. Click the View Credentials icon for the user for whom you want to view API Credentials.AS - View API Creds
  2. Copy and paste the required information into the relevant fields in your preferred API client. AS - View OAuth 2 CC Creds

You can view the API Credentials and Access Token URL required when requesting an OAuth 2.0 Access Token, on the API Credentials page, accessed from Admin Settings in the main MXO UI.

  1. Click the View Credentials icon for the user for whom you want to view API Credentials.AS - View API Creds
  2. Copy and paste the required information into the relevant fields in your preferred API client. AS - View OAuth 2 CC Creds

Example HTTP Authorization Header

As part of your request, you must provide an authorization header. The authorization header is constructed, as follows:

  1. Combine your MXO Client ID and Client Secret into a string "clientID:clientSecret".
  2. Encode the resulting string using the RFC2045-MIME variant of Base64.You are not limited to 76 characters per line.
  3. When creating your header, add the authorization method, Basic, and a space before the encoded string.

For example, using the Client ID and Client Secret shown above, the header is formed as follows:

Authorization: Basic MmU4ZmVjMGUtMzRmYi00ODUxLTgwMGUtOTk4OTMzMWU1NWQ  
yOmQ3ZjQ0ODRmLTk4MTctNDc3OC05MTYxLTZlYjA2ZDFmNmNmNw==

Example Request

ParameterDetails
Request MethodPOST
Request URLhttps://myoneserver.thunderhead.com/one/oauth2token
Request HeadersAuthorization header: HTTP Basic. Generated using the credentials supplied for the request, encoded in Base64. Example: Authorization: Basic MmU4ZmVjMGUtMzRmYi00ODUxLTgwMGUtOTk4OTMzMWU1NWQ yOmQ3ZjQ0ODRmLTk4MTctNDc3OC05MTYxLTZlYjA2ZDFmNmNmNw== Content-Type: application/x-www-form-urlencoded
Request Body 
grant_type=client_credentials

Example Response

Expected Response Code

200 SUCCESS

Expected Response Body

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRUeXBlI   joxLCJ0ZW5hbnRMb2NhbGUiOiJlbl9VUyIsImZlYXR1cmVzIjoiM3w2MDEwfDYwMjB8NjAz MHw2MDUwfDYwNTF8NjA1Mnw2MDUzfDYwNTR8NjA1NXw2DYwOTciLCJzY29wZSI6W10sInRl bmFudGlkIjo1ODE3NDk4NzgyODYxMTAyNTUxLCJ1c2VyQXV0aG9yaXRpZXMiOlsiOCIsIjEi LCIyIiwiOTAxIiwiMTEwMCJdLCJleHAiOjE1MDMzMDY5NzEsInVzZXJpZCI6ImFwb3BAb2Nvbi1z YW5kYm94IiwianRpIjoiMWE5YjE4NTYtNDBiMC00NWQ4LTk3NTgtOGQxN2E4MWMxOWE3IiwiY2 xpZW50X2lkIjoiYXBvcEBvY29uLXNhbmRib3gifQ.vRLRFxiMG5l7CwITCYgj2bndwa2j5PQ1C  
    WGPL0H3xpY"
    "token_type": "bearer",
    "expires_in": 299,
    "jti": "1a9b1856-40b0-45d8-9758-8d17a81c19a7"
}