Authenticate to the Enterprise CX API

Enterprise CX · Guides · 10 min

Configure OAuth Resource Owner Password or API-key authentication and make your first Enterprise CX API request.

Enterprise CX supports two ways to authenticate API requests:

Method	What you send
OAuth Resource Owner Password	Exchange a user's credentials and OAuth client credentials for an access token, then send that token with API requests.
API key	Send a key associated with an Enterprise CX user in the x-api-key header. Enterprise CX handles the underlying token authentication internally.

This guide walks through both methods using Postman, an application for sending API requests and viewing responses. Choose the workflow that matches your integration. Each ends with a GET request to retrieve data.

Before you begin

You need:

• Access to Enterprise CX to configure users and groups, plus an OAuth client or API key for your chosen method. Customers can create their own users, groups, and OAuth clients.
• Postman to follow the examples.
• The API base URL and a GET endpoint your user is permitted to access.
• For OAuth, the token URL and any additional token-request settings required by your environment.

The examples use placeholders because the URLs and test endpoint have not been specified. Obtain the values for your Enterprise CX environment before sending a request.

Placeholder	Replace with
<BASE_URL>	Your Enterprise CX API base URL, without a trailing slash.
<API_ENDPOINT>	The path of a GET endpoint you can access, without a leading slash.
<TOKEN_URL>	The full URL used to request an OAuth access token.

Replace the angle brackets and the text inside them. Do not send the placeholders as literal values.

A few API basics

An API request is a message your application sends to Enterprise CX. The URL identifies the resource you want to access. The method describes the action; this guide uses GET to retrieve data. A header carries information with a request, such as your access token or API key. The response is the status and any data Enterprise CX sends back.

How permissions work

Enterprise CX assigns permissions to groups. Users receive permissions by belonging to those groups. If a user belongs to multiple groups, their permissions are the combination of the permissions from all those groups.

Both authentication methods act on behalf of a user. For OAuth, the client's scopes also determine which APIs the client can access. Obtaining a token or creating a key does not grant access to every API.

Treat passwords, client secrets, access tokens, and API keys as sensitive credentials. Store them securely and do not include them in public code, documentation, or screenshots.

Method 1: OAuth Resource Owner Password

This method uses an Enterprise CX username and password together with an OAuth client to obtain a temporary access token.

1. Configure a group and user

1. In Enterprise CX, open the group management area.
2. Create a group, or select an existing group, with the permissions needed for your test API resource.
3. Open the user management area and create a user for your integration, or select an existing user.
4. For a new user, set a username and password.
5. Assign the user to the group or groups that provide the required permissions, and save the configuration.

The user's group membership determines what they can access. A special group is not required solely to obtain a token.

2. Configure an OAuth client

1. Open the OAuth client configuration area in Enterprise CX.
2. Create a client and select the Resource Owner Password flow.
3. Configure the client to use a secret for this walkthrough, and securely record its Client ID and Client Secret.
4. Add the scopes that provide access to the API you intend to call, and save the configuration.

Redirect URI and CORS settings do not apply to this flow.

Enterprise CX allows clients to be configured with or without a secret. This walkthrough follows the demonstrated configuration, which uses a client secret.

3. Request an access token

In Postman, open a request's authorization settings, select OAuth 2.0, and use the option to request a new access token. Supply these values:

Setting	Value
Grant type	Password, also called Resource Owner Password Credentials
Access token URL	<TOKEN_URL>
Username	Your Enterprise CX user's username
Password	That user's password
Client ID	Your OAuth client's ID
Client Secret	Your OAuth client's secret

Use your environment's token-request instructions for any additional settings, including how to send the client credentials and whether to enter a scope value in Postman. Those settings are not specified here. Do not guess them or substitute the API base URL for the token URL.

Submit the token request. When authentication succeeds, you receive an access token. Keep it available for the next step.

Access tokens expire. If your token expires before you use it, repeat this step to obtain a new one. No fixed token lifetime is assumed in this guide.

4. Make a successful GET request

1. Create a request in Postman and set the method to GET.

2. Enter the URL below, replacing both placeholders:

   <BASE_URL>/<API_ENDPOINT>

3. In the request's authorization settings, select Bearer Token and paste the access token. Paste only the token; Postman adds the Bearer prefix.

4. Send the request.

The request uses this authorization header:

Authorization: Bearer <ACCESS_TOKEN>

Check the response status and body in Postman. A successful response with the data expected for your chosen endpoint confirms that the request authenticated and had permission to access that resource. The exact status and response format depend on the endpoint.

If the request does not succeed, check the URL, token expiration, user's group permissions, and client's scopes, then send the request again. Once the GET request succeeds, you have completed the OAuth workflow.