How to Make Adaptive REST API Calls for Platform Customers with User Sync Enabled

If you’re a platform customer (HCM + FINS + Adaptive) or using Workday HCM or Financials alongside Adaptive and want to create custom scripts leveraging Adaptive’s REST API (XML), you’ve likely encountered a key requirement: providing Adaptive user credentials (username and password). For standalone customers or those not using user sync, this typically involves creating an integration user in Adaptive. Easy peasy.

But what if you’re using user sync? How do you supply credentials for API calls in the XML input?

In this article, I’ll guide you through the steps to generate the necessary credentials when user sync is enabled. I’ll also share helpful links to official documentation to ensure a smooth integration process.

1. Overview

The process allows Workday-synchronized users to make API calls to Adaptive Planning using Workday credentials. The key steps involve:

Generating an OAuth token using Workday's API.
Using this token (instead of a username and password) in Adaptive API requests.

This is essential for organizations where user synchronization is enabled between Workday and Adaptive Planning, as standalone Adaptive credentials cannot be created.

2. Key Concepts

Integration System User (ISU): A special type of user set up specifically for integrations. For API access, this ISU must:
- Be created in Workday.
- Be mapped to an Adaptive Planning user account.
- Have the necessary permissions.
Certificates: Used to ensure secure authentication between Workday and Adaptive APIs.
Tokens:
- Workday Access Token: Generated using the JWT and used to retrieve the Adaptive-specific API token.
- AdaptiveAPIAccessToken: A token that allows interaction with Adaptive APIs.

3. Prerequisites

Before proceeding:

Workday Security Domain and Groups: Ensure ISUs are added to the correct security domain for API access: Set up: Adaptive Planning API Access.
Workday Setup:
- Enable Single Sign-On (SSO) and Public API options for Adaptive Planning (within the User Sign-on tab, in the Adpative Planning tab)
- Create and map the ISU to an Adaptive Planning user account.
Adaptive Setup:

Verify the ISU (starting with PublicAPIISU_) appears in the Adaptive Planning users list and has the required permissions.

4. Step-by-Step Process

Step 1: Get a Certificate and Extract Public Key

Generate or acquire an X.509 certificate in Workday.
- Extract the public key to upload to Workday.
- Retain the private key for signing the JWT (used in the script).

Step 2: Register an API Client in Workday

Register a new API client in Workday with these details:
- Grant Type: JWT Bearer Grant.
- Scope (Functional Area): Adaptive Planning.
- X.509 Certificate: Upload the public key from Step 1.
After registration, note the following details for later:

Workday REST API Endpoint.
Token Endpoint.
Authorization Endpoint.

More info on how to register an API client on Workday's documentation - click here. --> you need a community account to access this documentation

Step 3: Generate Tokens with CURL examples

Generate a JWT Workday Access token:
- In your script, use your private key to generate a signed JWT with the required claims (iss, sub, aud, and exp). Examples are provided on Workday's documentation here (open documentation)

Retrieve Workday Access Token:

Make a POST request to the Token Endpoint with the JWT.
Example of an endpoint: https://{host or gateway}/ccx/oauth2/{tenant}/token

curl --request POST 'https://{host}/ccx/oauth2/{tenant}/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
--data-urlencode 'assertion={{jwt_assertion}}'

Retrieve AdaptiveAPIAccessToken:
- Use the Workday Access Token to fetch the Adaptive-specific token from the appropriate Workday endpoint.
- Example:

https://{host or gateway}/ccx/api/planning/v1/{tenant}/adaptiveAPIAccessToken

curl --request GET 'https://{host or gateway}/ccx/api/planning/v1/{tenant}/adaptiveAPIAccessToken' \
--header 'Authorization: Bearer {{the prior access_token value}}' \
--data-raw ''

Step 4: Adaptive Planning API

Use the AdaptiveAPIAccessToken in the credentials element of your Adaptive API request XML.
Example from Workday's doc:
curl -H "Content-Type: text/xml" -d '<?xml version='1.0' encoding='UTF-8'?><call method="exportLevels" callerName="a string that identifies your client application"><credentials token="ID eyJhbDci0iJSUzUxMiIsUmtpZCI6IdvcmtkYXlfa2V5In0.eyJpc3KiOiJXb3JrZGFZIiwiYXV0aF90aW1lIjoxNTczMTY3NjU2LBjzeXnfynnJd.bztQzBmHeTj1amnHA96TdrJK0MXMghUFF1KyjxqIq63Eche7SEcoZBVGX4wJgna106pmCqgrrVWMf13Hg_sb_szabal2XN1KEEk1qh8z1IDlbt6qJIL_xyW3J2nNSs5ima3vJUYU5sRQXwXst0GuFWXpy464GyB4oKcscrg28X3dnPO_ytdohMKHsWkqyHQKXFQwoQUj0lpOZX8C9oBHDYA58IXxGkqKLJVNPvDND6rGY5fTHQ-yxpe1nz-WqB0boiq9a-dv8b3EBzbelxj2fCPdMbng6kzygDcA2at_7BNQiyzfIovS5AG"/><include versionID="3" inaccessibleValues="false"/><sheet id="3" /></call>' -X POST https://api.adaptiveplanning.com/api/v23

The XML in a more readable way is basically:

<call method="exportLevels" callerName="ClientApp">
<credentials token="Your_Adaptive_API_Access_Token"/>
<include versionID="123" inaccessibleValues="false"/>
<sheet id="99" />
</call>

Go to the official documentation for more details and view script examples.

Their online doc provides 2 examples, one in Java and one in C#.

Java: Sample code provided to generate a JWT token, call Workday API, and use the tokens for Adaptive requests.
C#: Similar functionality to the Java script, leveraging libraries for JWT generation and signing.

How it Works - summary

JWT Authentication:
- Ensures secure and temporary access to Workday APIs.
Token Exchange:
- Workday Access Token authenticates against Workday.
- AdaptiveAPIAccessToken allows interaction with Adaptive Planning APIs.
XML API Requests:

Once the Adaptive token is acquired, it's included in API calls to access or modify data in Adaptive Planning.

Example in Python

import jwt 
import time

# Inputs
private_key_file = "path/to/private_key.pem"  # Path to your private key file
client_id = "your-client-id"                 # The client ID from Workday API client registration
isu = "your-isu"                             # The Integration System User (ISU)
audience = "wd"                              # The audience, typically "wd"
expiration_time = 300                        # Token validity in seconds

# Generate JWT
def generate_jwt(client_id, isu, audience, private_key_file, expiration_time):
    # Read private key
    with open(private_key_file, "r") as key_file:
        private_key = key_file.read()
    
    # Define JWT claims
    payload = {
        "iss": client_id,                    # Issuer
        "sub": isu,                          # Subject
        "aud": audience,                     # Audience
        "exp": int(time.time()) + expiration_time  # Expiration time (current time + 300 seconds)
    }
    
    # Generate JWT token
    token = jwt.encode(payload, private_key, algorithm="RS256")
    return token

# Generate the token
try:
    jwt_token = generate_jwt(client_id, isu, audience, private_key_file, expiration_time)
    print("Generated JWT Token:")
    print(jwt_token)
except Exception as e:
    print("Error generating JWT:", str(e))

Explanation

Private Key:
- The private_key.pem file contains the private key you use to sign the JWT.
- This key corresponds to the public key uploaded to Workday during the API client registration.
Payload (Claims):
- iss: Client ID provided by Workday.
- sub: The ISU you created for API access.
- aud: "wd" is the standard audience for Workday.
- exp: Expiry time in seconds from the current Unix timestamp.
Signing:
- The jwt.encode() method signs the token using your private key and the RS256 algorithm.
Output:
- The output is a JWT that you can use in Workday API requests.

Sample Output

Here’s an example of what the token might look like:

eyJhbGciOiJSUzI1NiIsInR5cyJpc3MiOiJ5b3VyLWNsaWVudC1pZCIsInN1YiI6InlvdXItaXN1IiwiYXVkIjoid2QiLCJleHAiOjE2ODk3MTIwMDB9.NjM2YzAx...

Workday Adaptive Wiz

Adaptive REST API Calls for Platform Customers with User Sync Enabled