Authenticating APIs with OAuth

Medallia Experience Cloud security framework uses OAuth 2.0 for authenticating access to data. Applications that access the Experience Cloud APIs are OAuth clients. Each OAuth client receives these credentials:

  • Client ID — Unique identifier for the client, and passed to the server as the clientId parameter when authenticating with the authorization server.

  • Client Secret — Pre-authenticated identification associated with the client, and passed to the server as the clientSecret parameter when authenticating with the authorization server.

  • OAuth Token Endpoint (API endpoint) — URL to the OAuth server's token-endpoint for the company; where applications request tokens. It will have this format similar to this: https://instance.medallia.com/oauth/companyName/token.

Important: Contact your Medallia expert to get access to an instance and to get your the client credentials. Your expert will:
  • Enable API access for the instance, if it is not already enabled.

  • Create application and OAuth accounts for your application, and provide the:
    • Client ID.

    • Client secret.

    • OAuth endpoint.

Applications pass the client ID and secret to the OAuth token endpoint in return for an access (bearer) token, which is used when requesting resources from the resource server.

Application passes clientId and clientSecret to token endpoint to get the access (bearer) token, which is then used when requesting resources

Requesting OAuth authorization (getting a token)

Applications request authorization for access to a company from the company's OAuth authorization endpoint, which is a URL in this format: https://instance.medallia.com/oauth/companyName/token. For example, https://queryapidemo.demo.sc4.medallia.com/oauth/myCompany/token.

When requesting the token, pass in the client ID and secret values as username and password arguments when making the request.

cURL example

For curl, use this template:

curl <TOKEN_URL> -X POST -u 'CLIENT_ID:CLIENT_SECRET' -d grant_type=client_credentials

For example, in this curl invocation the Client ID and Client secret are querydemo and query12345:

curl https://queryapidemo.demo.sc4.medallia.com/oauth/fs/token -X POST -u 'querydemo:query12345' -d grant_type=client_credentials

Alternatively, you can use this template to specify each value as a data element:

curl <TOKEN_URL> -X POST -d client_id=CLIENT_ID -d client_secret=CLIENT_SECRET -d grant_type=client_credentials

In which case the example looks like this:

curl https://queryapidemo.demo.sc4.medallia.com/oauth/fs/token -X POST -d client_id=querydemo -d client_secret=query12345' -d grant_type=client_credentials
Note: The second example is more versatile, but is not supported by all curl implementations.

Java client example

This Java example uses the Google OAuth client to pass client ID (key) and secret to the endpoint to request a bearer token. The Client ID and Client secret are querydemo and query12345:

  1. Add Google Gradle dependencies to your build.gradle project file:

    compile 'com.google.oauth-client:google-oauth-client:1.23.0'
    compile 'com.google.http-client:google-http-client-jackson2:1.23.0'
  2. Obtain an access token by authenticating to the corresponding token endpoint:

    import com.google.api.client.auth.oauth2.BearerToken;
    import com.google.api.client.auth.oauth2.ClientCredentialsTokenRequest;
    import com.google.api.client.auth.oauth2.ClientParametersAuthentication;
    import com.google.api.client.auth.oauth2.Credential;
    import com.google.api.client.auth.oauth2.TokenResponse;
    import com.google.api.client.http.GenericUrl;
    import com.google.api.client.http.HttpRequestFactory;
    import com.google.api.client.http.HttpResponse;
    import com.google.api.client.http.javanet.NetHttpTransport;
    import com.google.api.client.json.jackson2.JacksonFactory;
    
    import java.io.IOException;
    
    public class SampleApplication {
    
        public static void main(String[] args) throws IOException {
            String accessToken = getAccessToken("https://queryapidemo.demo.sc4.medallia.com/oauth/fs/token", 
                                                "querydemo", "query12345");
            System.out.println("Access token: " + accessToken);
        }
    
        private static String getAccessToken(String tokenUrl, String clientId, String clientSecret) throws IOException {
        TokenResponse response =
           new ClientCredentialsTokenRequest(
               new NetHttpTransport(),
               new JacksonFactory(),
               new GenericUrl(tokenUrl))
               .setGrantType("client_credentials")
               .setClientAuthentication(
               new ClientParametersAuthentication(
                   clientId, clientSecret))
               .execute();
    
        return response.getAccessToken();
    
    }
    Once you have obtained an access token, you can use it to request resources. For more information, see Making an API call using the access (bearer) token.