Getting Started

This page helps you start integrating with CXone Mpower. It explains the tasks you must perform to start building an integration. To get started and make CXone Mpower API calls, you have five tasks:

  1. Plan your integration
  2. Submit your registration form
  3. Prepare a test user account in CXone Mpower
  4. Set up authentication
  5. Perform API discovery
  6. Best Practices

You can also use these pages to help you get started integrating with CXone Mpower:

Task 1: Plan Your Integration

  • Consider your use-case:

    Clearly define the purpose of your integration. This helps you understand the actions that your integration (or users of your integration) will perform. It also gives you an idea of which CXone Mpower APIs you’ll use.

  • Determine your application type:

    For more information about application types, see the authentication overview.

    NICE considers your integration either a back-end app or client-side app.

    • Back-end apps entail server-to-server communication. These require you to set up standard OAuth2.0 application authentication.
    • Client-side apps require you to set up OpenID Connect. OpenID Connect provides a user login flow, which prevents credentials from being handled by your application.

    You should also determine if your integration will be for a single CXone tenant or multiple CXone tenants. Use the examples in the following drop-down to better understand the tenancy of your use-case.

    Your application may need to authenticate users from multiple tenants or customers. You must determine this when registering your app with NICE. For example, if your application is productized and intended to deploy to distinct customers, you should choose Multiple Tenants so that your single registration will work across any tenant within the selected environments. Alternatively, your application may be developed to provide capability for a specific tenant and Single Tenant is appropriate.

    • Example 1:

      An app developer wants to create an agent client. The client will integrate their platform with CXone Mpower. The agents must log in to use the client, so the developer needs to set up OpenID Connect. The developer plans to sell it to multiple customers, therefore, the developer selects Multiple Tenants when registering the app with NICE.

    • Example 2:

      A business using CXone Mpower wants to create a custom reporting app for their internal employees. This will compile data from multiple sources, including CXone Mpower. NICE considers this a back-end application, since it entails server-to-server communication with CXone Mpower. This means they must set up standard OAuth2.0 authentication. The app will be built specifically for the business to use internally, therefore, they only need it for their single tenant.

    • Example 3:

      An enterprise organization has CXone Mpower tenants around the world. They want to integrate a custom Bring Your Own Channel (BYOC) channel that will be available to all their CXone Mpower tenants. The channel does not require a user login flow, therefore, it is a back-end application and they must set up standard OAuth2.0. They want it available to all of their CXone Mpower tenants, so they select Multiple Tenants in their registration form.

    • Example 4:

      An app developer wants to integrate CXone Mpower media recordings into their 3rd party platform. They plan to sell the app to businesses using CXone Mpower, therefore, they select Multiple Tenants in their registration form. The app will ingest data from each customer and display it on a personalized dashboard. To do so, the app communicates with the back-end of CXone Mpower and does not require a user login flow, therefore they must set up standard OAuth2.0 authentication.

  • Map out your APIs:

    Check out the CXone Mpower APIs documented on the developer portal. Depending on your preferred workflow, you can create a map or list of the specific endpoints you plan to use. You can also make test API calls to your CXone Mpower system from the documentation.

  • Identify your technical contacts:
    You must provide NICE with a list of technical contacts. These are the contacts that NICE will communicate with about your integration. Compile a list of email addresses.

Task 2: Submit Your Registration Form

When your plan is ready, you must submit an Application Registration form to NICE. This provides NICE with details about your integration. For example, you’ll specify its purpose, the API groups you plan to use, your authentication type, and so on. After submitting your form, NICE auto-generates a tracking number.

After processing your application, NICE responds back with credentials for you to set up authentication. These credentials are unique to your application and should be used for all authentication calls within the environment they’re issued.

NICE typically takes 2-3 business days to process a registration. If the technical contacts don’t receive a response within this time frame:

  • Check your email spam folder.
  • Contact DEVone Support or your CXone Mpower Account Representative.

If necessary, be sure to include your tracking number with any emails about your registration.

The following table explains technical configuration details that you must provide in your registration form. The form includes other pieces of information not explained here, like a name for your app.

FIELD DETAILS
Business Unit Your organization's CXone Mpower business unit (BU) number. If you have multiple business units, you must provide the BU number of your organization's primary BU. For example, DEVone partners have a primary BU in addition to any of their customers' BUs. You can find your BU number in CXone Mpower:
  1. In CXone Mpower, click the app selector and select ACD.
  2. Go to ACD Configuration > Business Units.
  3. Locate the Unit Number in the Details tab.

If you have questions on which BU number to use, contact your CXone Mpower Account Representative.

Technical Contacts Personnel in your organization who are the points of contact for your integration. CXone Mpower sends notifications about your app to these addresses, including app registration details. NICE may also periodically contact these personnel to ensure that the email addresses are still active.
Tenancy

Indicate whether your integration will authenticate users for a single tenant or multiple tenants.

If you’re building an application that will be used by multiple tenants or customers, you must select Multiple Tenants.

Tip
This app registration process provides you with a client_id and client_secret. The secret and ID are unique to your application and should be used for all authentication calls within the environment they’re issued.
CXone Mpower Environments

If you selected Multiple Tenants for the tenancy, you must indicate whether your app will be used for a government environment.

If you selected Multiple Tenants for the tenancy, you must indicate which environments your application will support. For each environment your app will be registered in, NICE provides a set of credentials.

Authentication Method

Indicate which OAuth2.0 method your integration will use. The main distinction between the options is that with client_secret_jwt, you're providing the information packaged as a JWT instead of JSON body parameters.

  • client_secret_post
  • client_secret_basic
  • client_secret_jwt

Refer to the OAuth2.0 specification to find out which option to choose. You can also refer to the authentication overview for more information.

Origins

If you plan to build User: Public or User: Confidential application types, enter a list of locations where the application runs.

By default, CXone Mpower API servers block API calls coming from origins, or applications, that are not pre-approved. This causes failures even if the request is valid. CXone Mpower uses Cross-Origin Resource Sharing (CORS) for security. Ensure that you provide a comprehensive list of origins to prevent blocked requests.

Scope You must identify which groups of APIs your app will use. This is only relevant if you're using Central CXone Mpower.
Application Type NICE categorizes your app in one of three categories: Back-End, User: Public, or User: Confidential. The majority of integrations are back-end apps. The authentication overview provides more explanation on these three categories and the type of authentication you must use.

Task 3: Prepare a Test User Account

If you're building a back-end integration:

You need to create a user account in CXone Mpower. Your app interacts with CXone Mpower through this API user account. The account should have:

  • A unique role with the minimum permissions enabled. Best practice is to assign permissions only for the actions that the app will perform.
  • No login authenticator assigned.

You must also request an administrator to generate an Access Key ID and Access Key Secret from this account’s settings. During the authentication process, your app must provide these credentials to the authentication server. The drop-down below provides instructions on creating an account and generating an access key ID and secret.

Tip
You may not need these credentials until later in the development phase. In this case, you can write the authentication in your app, then create the user later for testing and production.
  1. Click the app selector and select Admin
  2. Click Employees > Create Employee.
  3. Enter the employee's First Name and Last Name. The Middle Name is optional. Special characters are not accepted in these fields, including, but not limited to: ! / < > ? % ".
  4. Enter the Username you want to assign the account. The username must be in the form of an email address. The field is auto filled from the Email Address field. You can edit it if you want to.
  5. Assign a Primary Role to an employee from the drop-down.
  6. If you are setting up OpenID Connect, select the Security tab then select a login authenticator.
    Important
    Employees can only log into CXone Mpower if they are assigned to a login authenticator. Accounts for back-end applications should not have a login authenticator assigned.
  7. Click Create to create the employee profile and continue setting it up. Click Create & Invite if you're ready for the user to activate their account and set up their password.

If you are creating a back-end application, you must create an access key for the integration user. Perform the following steps to create the access key. To do so, your CXone Mpower account must have Edit enabled in the My Access Key or Access Key permission. Permissions are handled in your CXone Mpower account's role . You, or an administrator, can view role or security profile permissions in the Admin application.

To make the POST request for an access token, you must use the endpoint URL appropriate for your system's region. Contact your CXone Mpower Account Representative if you're uncertain which region to use. You can use one of the following:

  1. In CXone Mpower, click the app selector and select Admin > Employees.
  2. Select your user account.
  3. Click the Security tab.
  4. Click Generate New Access Key.
  5. Click SHOW SECRET KEY.
  6. Copy the secret to a text editor like Notepad or Word.
  7. Save the secret somewhere safe where you can access it again.
    Warning
    After you navigate away from your profile, you will not be able to view your access secret again.

If you're building a user application:

Create a CXone Mpower user account that resembles the persona that would use your app. For example, if you're building an agent client, create an account that resembles an agent. It must have a login authenticator assigned, which prompts the user to sign in.

Tip
You may not need these credentials until later in the development phase. In this case, you can write the authentication in your app, then create the user later for testing and production.
  1. Click the app selector and select Admin
  2. Click Employees > Create Employee.
  3. Enter the employee's First Name and Last Name. The Middle Name is optional. Special characters are not accepted in these fields, including, but not limited to: ! / < > ? % ".
  4. Enter the Username you want to assign the account. The username must be in the form of an email address. The field is auto filled from the Email Address field. You can edit it if you want to.
  5. Assign a Primary Role to an employee from the drop-down.
  6. If you are setting up OpenID Connect, select the Security tab then select a login authenticator.
    Important
    Employees can only log into CXone Mpower if they are assigned to a login authenticator. Accounts for back-end applications should not have a login authenticator assigned.
  7. Click Create to create the employee profile and continue setting it up. Click Create & Invite if you're ready for the user to activate their account and set up their password.

Task 4: Set Up Authentication

If your app needs to authenticate end-users, set up OpenID Connect (OIDC). If not, set up standard OAuth2.0.

The authentication overview provides more details about authentication and authorization in CXone Mpower.

  1. Determine your issuer URL. Use one of the following:
    • Global Production Environment: https://cxone.niceincontact.com
    • FedRAMP Moderate Environment: https://cxone-gov.niceincontact.com
    • Australian Sovereign Environment: https://nicecxone-sov1.au
    • EU Sovereign Environment: https://nicecxone-sov1.eu
  2. Append the string /.well-known/openid-configuration to the issuer.
  3. Make an HTTP GET request against the combined string which returns a JSON object. The following is an example of the JSON object returned when requesting the OpenID Connect configuration of the NICE global issuer: 

    curl --location 'https://cxone.niceincontact.com/.well-known/openid-configuration'

    // Response:
    {
    "issuer": "https://cxone.niceincontact.com",
    "authorization_endpoint": "https://cxone.niceincontact.com/auth/authorize",
    "token_endpoint": "https://cxone.niceincontact.com/auth/token",
    "userinfo_endpoint": "https://cxone.niceincontact.com/auth/userinfo",
    "jwks_uri": "https://cxone.niceincontact.com/auth/jwks",
    "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post"
    ],
    "token_endpoint_auth_signing_alg_values_supported": [
    "RS256"
    ],
    "end_session_endpoint": "https://cxone.niceincontact.com/auth/authorize/logout",
    "scopes_supported": [
    "openid"
    ],
    "response_types_supported": [
    "code"
    ],
    "subject_types_supported": [
    "public"
    ],
    "id_token_signing_alg_values_supported": [
    "RS256"
    ],
    "request_object_signing_alg_values_supported": [
    "none"
    ],
    "display_values_supported": [
    "page",
    "popup"
    ],
    "claim_types_supported": [
    "normal"
    ],
    "code_challenge_methods_supported": [
    "S256"
    ]
    }

Retrieve an Access Token

The steps for retrieving an access token are different for standard OAuth and OpenID Connect. Follow the steps for your authentication method of choice.

For this flow, you must provide an Access Key ID and Access Key Secret to the authentication server. You can generate these from a CXone Mpower user account. See Task 3 for more information.

  1. Review the JSON block returned during the authentication discovery process, explained in the previous section. Locate the token_endpoint.
  2. Create a POST request to the value of token_endpoint. This value is the full URL you should use for the /auth/token endpoint.
  3. Include your authentication credentials in the POST request. The way in which you include these credentials depends on your authentication method you selected in your registration form.
    If you selected client_secret_basic as your authentication method in your app's registration:
    1. Add a basic authorization header containing your application's client ID and client secret.
    2. Add an x-www-form-urlencoded body containing the following key:value pairs.
      • grant_type: password
      • username: {access_key_id}
      • password: {secret_key}

    If you selected client_secret_post as your authentication method in your app's registration:

    1. Add an x-www-form-urlencoded body containing the below key:value pairs
      • grant_type: password
      • username: {access_key_id}
      • password: {secret_key}
      • client_id: {client_id}
      • client_secret: {client_secret}
  4. Refresh the token when necessary by repeating this process.
Tip
The token response includes a time-to-live (TTL). Be sure to plan the renewal of the authentication token (refresh token) before 5 minutes of access token expiry.

Learn more about OpenID Connect on the authentication overview.

OpenID Connect flows entail a series of redirects. The user must be redirected to a webpage that lets them enter their user credentials. This can be either a CXone Mpower username and password or credentials from a federated identity provider. Then, the user can be redirected back to the authorization endpoint.

  1. Review the JSON block returned during the authentication discovery process, explained in the previous section. Locate the authorization_endpoint.
  2. Create a POST request to the value of authorization_endpoint. This value is the full URL you should use for the /auth/authorize endpoint.
    If you're setting up a PKCE flow, be sure to populate the code_challenge, code_challenge_method, and code fields in your request.
    * indicates a required parameter
    FIELD VALUE DETAILS
    scope* openid The only supported value for CXone Mpower API authentication.
    response_type* code The only supported value for CXone Mpower API authentication.
    client_id* application specific The value that NICE CXone Mpower provided upon approval of your app registration.
    redirect_uri* application specific This value changes based on your app. It is the URI that you want to redirect users to after they login with CXone Mpower user credentials.
    state application specific This value is for the use of the application.
    It's passed unmodified to the redirect callback. For example, this might be used to store the URL that the user is directed to after a successful login.
    display Either page or popup Determines if the CXone Mpower login page opens in a new browser tab or a separate window that pops up.
    max_age Integer Indicates how recently the user must have authenticated to continue using the current user session. This is optional for the initial auth flow and not allowed in other cases.
    Enter a value in seconds.
    When you include this parameter, the returned ID token includes an auth_time claim.
    id_token_hint A previously received id_token An existing id_token that you have already received. It identifies the user who must authenticate. This is optional for the initial auth flow and not allowed in other cases.
    If the identified user matches the current valid user session, then no user interaction is required. If the identity does not match or if there is no current state available, then a new session is started that is constrained to authenticate the identified user.
    This parameter takes priority of login_hint if both are present.
    login_hint Username This can be used to bypass the request for a username. The user may be able to change the username even with this parameter specified
    code_challenge Random string per PKCE standard A PKCE code challenge, described in section 4.3 of the PKCE standard. This is optional for the initial auth flow and not allowed in other cases.
    code_challenge_method S256 A PKCE code challenge method, described in section 4.3 of the PKCE standard.. This is optional for the initial auth flow and not allowed in other cases.
    tenantId The assigned tenant identifier This parameter is part of the CXone Mpower platform, not the OpenID Connect standard.
    The identifier for your CXone Mpower tenant that is requesting authentication. This lets you include branding customization to the CXone Mpower login page, like a unique banner. This is optional for the initial auth flow and not allowed in other cases.
  3. The user will be directed to the CXone Mpower global login page. This process is entirely controlled by CXone Mpower, aside from any customization parameters you provided in your POST request. Once the login process is completed, the user is redirected to the redirect_uri with an auth code or error.
  4. At the end of the OIDC flow, your POST request returns an auth code.
  5. Review the JSON block again, which was returned during the authentication process. Locate the token_endpoint.
  6. Create a POST request to the token_endpoint. This value is the full URL to the /auth/token endpoint.
    1. If you're developing a public app, use the auth code with the PKCE flow. For more information, in the /token documentation, you can select PKCE validation as the example request.
    2. If you're developing a confidential app, use the auth code with the client_secret_post or client_secret_basic flows. If you selected client_secret_basic as your authentication method in your app's registration:
      • Add a basic authorization header containing your application's client ID and client secret.
      • Add an x-www-form-urlencoded body containing the following key:value pairs.
        • grant_type: password
        • username: {access_key_id}
        • password: {secret_key}

      If you selected client_secret_post as your authentication method in your app's registration:

      1. Add an x-www-form-urlencoded body containing the below key:value pairs
        • grant_type: password
        • username: {access_key_id}
        • password: {secret_key}
        • client_id: {client_id}
        • client_secret: {client_secret}
  7. Refresh the token when necessary by calling the /token endpoint again and passing the refresh_token. The refresh token is returned from the /token endpoint. Tokens expire after a time specified in the expires_in parameter. This time may not always be the exact same number of seconds, each token exchange could return a different expiration time. Be sure to refresh the token before it expires.

Log Out Users

If you set up OpenID Connect, be sure to provide a way for users to log out. To do so, you must redirect the user to a specific URL. In the authentication discovery process, the returned JSON includes an end_session_endpoint field. The value of this field is the URL you can use to redirect the user when logging out.

Tip
The token response includes a time-to-live (TTL). Be sure to plan the renewal of the authentication token (refresh token) before 5 minutes of access token expiry

Task 5: Perform API Discovery

After getting your access token, you can perform API discovery. This helps you determine the appropriate base URL to use for subsequent API calls. You must build a base URL for your API calls, to which you can append your API endpoints. The following is an example base URL: https://api-na1.niceincontact.com. Below is the format, showing the individual components.

Base URL Format:
https://api-{area}.{domain}.com

  • https://api-: The request scheme and base URL prefix.
  • {area}: The area that your CXone Mpower instance is deployed in. If you're building an integration for your own organization, this value may not change. If you're building an integration that other organizations or tenants may use, this value may change and should be populated dynamically.
  • {domain} : The CXone Mpower domain retrieved during the discovery process.

API discovery entails extracting a tenant ID from the ID token in the /auth/token response, then querying the API discovery endpoint with the tenant ID. This returns the area and domain you should use in the base URL of your API calls. 


{
	"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjp7ImxlZ2FjeUlkIjoiQWRtaW5pc3RyYXRvciIsImlkIjoiMTFlYjAzNTgtNzQwOS0zZDIwLTgyZGYtMDI0MmFjMTEwMDAyIiwibGFzdFVwZGF0ZVRpbWUiOjE2ODY4NDE0NTYwMDAsInNlY29uZGFyeVJvbGVzIjpbXX0sInZpZXdzIjp7fSwiaWNBZ2VudElkIjoiMzAzODc1NDMiLCJpY1NQSWQiOiI4ODYiLCJzdWIiOiJ1c2VyOjExZWNlZTNmLTBkNTctMmNkMC04YWRmLTAyNDJhYzExMDAwMiIsImlzcyI6Imh0dHBzOi8vYXV0aC5uaWNlLWluY29udGFjdC5jb20iLCJnaXZlbl9uYW1lIjoiQmVvd3VsZiIsImF1ZCI6ImNkNjJiZTYxLTZhYTQtNDE3Yi04NTE4LWQ3MzVlYTM2NmUzZUBjeG9uZSIsImljQlVJZCI6NDYwMDczOCwibmFtZSI6ImJlb3d1bGZoZXJvdEBjbGFzc2ljcy5jb20iLCJ0ZW5hbnRJZCI6IjExZWIwMzU4LTcyNGItMzk3MC05N2U1LTAyNDJhYzExMDAwMyIsImZhbWlseV9uYW1lIjoiSGVyb3QiLCJ0ZW5hbnQiOiJkb2NfdGVhbV91aF9jbGFzc2ljczkyMDgyNDI5IiwiaWNDbHVzdGVySWQiOiJCMzIiLCJpYXQiOjE2ODY5NDAwMzUsImV4cCI6MTY4Njk0MzYzNX0.WD5yXN_Nxb_haxgKhqSJzcOuz7l6ezGNIFYGuFUmzlYg4vCnLZAxppGnAwvlfRT7lKtkM85fLK2xUZ-Bec1la_5uvUGObkQFnSTglLYS-q98K4AAyFFqUW1vg9J4smaLEB9hpQu9vjCLkO0BiSFfi4QXo1AHVYJHj0teswwoDhM",
	"token_type": "Bearer",
	"expires_in": 3600,
	"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJjZDYyYmU2MS02YWE0LTQxN2ItODUxOC1kNzM1ZWEzNjZlM2VAY3hvbmUiLCJpc3MiOiJodHRwczovL2N4b25lLm5pY2VpbmNvbnRhY3QuY29tIiwiaWQiOiIxMWVjZWUzZi0wZDU3LTJjZDAtOGFkZi0wMjQyYWMxMTAwMDIiLCJzZXNzaW9uSWQiOiI0NGNjYmZjMC0wNWY1LTQxMmUtODI4Zi0xZmM0NTBjN2FhMzkiLCJpYXQiOjE2ODY5NDAwMzUsImV4cCI6MTY4Njk0NzIzNX0.c9VmPHJWiBr_sBqKgrzn8dj1CKaqj-VU-LenFl3beAPs-re0Mkbfy6Cv1-VgQF8uzyiQsdua7xsrXcZ4BXXv0ojbdpbkrsp9t-ev1dBqEgatcSBYd06He1BPTvElJbeaLSMR2kpynz2eyvgh2AiKEK1VyztHKMcpZ1P0erqx8P4",
	"id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRlZmF1bHQifQ.eyJpY0FnZW50SWQiOiIzMDM4NzU0MyIsImljU1BJZCI6Ijg4NiIsInN1YiI6InVzZXI6MTFlY2VlM2YtMGQ1Ny0yY2QwLThhZGYtMDI0MmFjMTEwMDAyIiwiaWNEb21haW4iOiJuaWNlLWluY29udGFjdC5jb20iLCJpc3MiOiJodHRwczovL2N4b25lLm5pY2VpbmNvbnRhY3QuY29tIiwiZ2l2ZW5fbmFtZSI6IkJlb3d1bGYiLCJhdWQiOiJjZDYyYmU2MS02YWE0LTQxN2ItODUxOC1kNzM1ZWEzNjZlM2UiLCJpY0JVSWQiOjQ2MDA3MzgsInRlbmFudElkIjoiMTFlYjAzNTgtNzI0Yi0zOTcwLTk3ZTUtMDI0MmFjMTEwMDAzIiwibmFtZSI6ImJlb3d1bGZoZXJvdEBjbGFzc2ljcy5jb20iLCJmYW1pbHlfbmFtZSI6Ikhlcm90IiwidGVuYW50IjoiZG9jX3RlYW1fdWhfY2xhc3NpY3M5MjA4MjQyOSIsImljQ2x1c3RlcklkIjoiQjMyIiwidXNlcklkIjoiMTFlY2VlM2YtMGQ1Ny0yY2QwLThhZGYtMDI0MmFjMTEwMDAyIiwiYXJlYSI6Im5hMSIsImlhdCI6MTY4Njk0MDAzNSwiZXhwIjoxNjg2OTQzNjM1fQ.ZaLdWKOZt5__MnNNWw-7SAYoxzPipKsJ6xkNgpE8eZLpRd5eGWc212vTogdZ57CQa5_StmK61Zb28yUafSSIYNUAsLIe5x8MVJj5P2p2ujl6esUic7NkUq76hDg13vrGfakZqS41FM0dK2LvB9y9r5tt4oO_Q3w5KqkDiVz4zLA",
	"issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
Tip
The above base URL drives traffic through the API Façade.

The following steps explain how to manually dissect a token and extract the parameters within. This process should be automated within a production application.

  1. Use a JWT parser to extract the embedded fields within the ID token. From the ID token, you can see useful information regarding the tenant to which the user belongs. For this process, use the tenantId field.
  2. Using the tenantId field gleaned from your ID token, query the NICE API discovery endpoint to get information specific to your tenant:
    1. Construct the URL using the following pattern. Insert the tenant ID gained from the previous steps as a query parameter: 
      
    {issuer}/.well-known/cxone-configuration?tenantId={tenantId}
    2. Send a GET API request using the URL constructed in the previous step. An example response is shown below using tenantId from the example ID token. 
      
                    {
                    "private": false,
                    "area": "na1",
                    "cluster": "B32",
                    "domain": "niceincontact.com",
                    "acdDomain": "nice-incontact.com",
                    "uhDomain": "nice-incontact.com",
                    "ui_endpoint": "https://na1.nice-incontact.com",
                    "auth_endpoint": "https://na1.nice-incontact.com",
                    "api_endpoint": "https://api-na1.niceincontact.com",
                    "tenantId": "11eb0358-724b-3970-97e5-0242ac110003"
                    }
  3. To construct the base URL for NICE API calls made to this tenant, use the following pattern: api-{area}.{domain} where area and domain can be found from the discovery endpoint as shown above.
    For example, api-na1.niceincontact.com.
    The base URL for API calls should be dynamically constructed for each tenant to ensure that your application uses the correct URL. To reduce API call load, you can cache the resulting URL and periodically check to confirm that it is still valid.

After determining your base URL, you can append the individual endpoints for the APIs you want to use. You can copy the endpoints from the API's documentation. You can also sign in and try out the API from the documentation, which returns the fully qualified URL in the response.

Make API Calls

After completing the five tasks on this page, you should have:

  • The access token returned from the authentication process.
  • The base URL to use for all subsequent calls to CXone Mpower APIs.
To make CXone Mpower API calls:
  1. For request URLs, append API endpoints to the base URL.
  2. In API requests, include the access token in an authentication header.

Task 6: Best Practices

CXone recommends following Best Practices for quality and seamless integration with CXone applications.

  1. Do Not Open the Authorization Page Within an Iframe

    The CXone authorization flow is not supported when embedded inside an iframe due to security restrictions and browser compatibility issues. For optimal security and functionality, please ensure that the authorization page is opened in a top-level window or tab.

  2. Validate id_token After Login

    As per industry standards, client applications should validate the id_token immediately after a successful login. This ensures that the token is authentic, hasn't expired, and contains the correct claims. Only after validating the id_token should the application proceed with using the access token and refresh token to make API calls.

  3. Allow for Clock Skew Tolerance

    Client applications should allow for a clock skew tolerance of up to 5 minutes to ensure smooth token validation without issues arising from slight system time discrepancies.

  4. Do Not Impose Token Size Restrictions

    Token size in OIDC is not fixed and may vary based on claims, format, and signing mechanisms. Validating token size is not a standard practice and can break client applications. Instead, focus on proper token validation, such as signature, expiration, issuer, and audience checks.