Authentication

The Medallia Experience Cloud APIs use OAuth 2.0 for authenticating access to data and API endpoints. To access Medallia APIs, you will need a client ID and a client secret. Reference the product documentation for creating these.

Common OAuth 2.0 terminology:

• Client ID — The unique identifier for the account, passed to the authorization server as the HTTP Basic Authentication username
• Client secret — The secret key associated with the account, passed to the authorization server as the HTTP Basic Authentication password
• Access token — The granted token from the authorization server that must be used in subsequent HTTP requests to access resources

📘

Credentials are unique per environment

Your client ID and client secret are per instance. Your production environment, sandbox, and developer environments do not share client ID and secrets; you will need to generate new credentials for each instance.

Requesting a Token

Start by finding the OAuth 2.0 authorization endpoint, /oauth/_companyName/token_ on the Medallia Experience Cloud instance.

🚧

OAuth 2.0 tokens are issued by the MEC reporting instance

APIs are accessed via the Medallia API Gateway, but tokens are issued by the MEC reporting instance.

Next, issue an HTTP request similar to the below, using the client id and client secret as parameters to the HTTP Basic Authentication header:

export REPORTING_INSTANCE="instance.medallia.com"
export TENANT_NAME="tenant"

curl \
  "https://${REPORTING_INSTANCE}/oauth/${TENANT_NAME}/token" \
  -X POST \
  -u 'client_id:client_secret' \
  -d 'grant_type=client_credentials'

POST /oauth/tenant/token HTTP/1.1
Host: https://instance.medallia.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

grant_type=client_credentials

If the credentials are valid, we should get back the following type of response:

{
  "access_token": "2c5822312345678901d21",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the token_type and access_token values for subsequent API calls by passing them in the Authorization header as shown below:

curl \
  https://instance-tenant.apis.medallia.com/admin/v1/users/cc_executive \
  -X GET \
  -H 'Authorization: Bearer 2c5822312345678901d21'

Permissions and Access Scope

An OAuth account's permissions are shaped in two ways. When creating your client ID, a role is assigned to it. The role denotes (1) which actions you can take and (2) what data the client ID can access. Data access is only applicable to the use of the Query API, which is used to extract data and analytics from Medallia Experience Cloud.

See product documentation for generating your OAuth 2.0 credentials. Login to your Experience Cloud instance to access our product documentation.