Test Workday RaaS Reports with OAuth

Two things I love about OAuth in Workday are (1) Easier reviews with IT security because you said the “O” word and (2) easier IP restriction config.

What I don’t like is the DevEx around testing RaaS reports over OAuth. It’s not as simple as just opening a web page and entering your username+ & password. The rest of this post is all about setting up and testing RaaS API requests with OAuth. If you trust Workday Community more than me, you can just read: Steps: Authenticate RaaS with OAuth 2.0.

1. Create or identify a RaaS report to test

Get the XML, JSON, or CSV URL for the report.

2. OAuth Client Setup in Workday

You need to register your “app” (even if it’s just a test script) as an API Client.

  1. Register API Client: Search for the task Register API Client for Integrations.

    • Client Name: Something descriptive (e.g., Reporting_Automation_OAuth).
    • Grant Type: Select RefreshToken.
    • Access Token Type: Bearer.
    • Scopes: Select the functional areas your report touches (e.g., Staffing, Human Resources). There might be report data sources or report fields secured to core Workday domains that aren’t in any functional areas. If so, select the Include Workday Owned Scope check box.
  2. Save Credentials: Once you hit OK, Workday will show you a Client ID and Client Secret.

    Note: Copy the Client Secret immediately! Workday will never show it to you again.

  3. Generate a Refresh Token:

    • Search for Manage Refresh Tokens for Integrations.
    • Select the Integration System User (ISU) that owns the report.
    • Select your new API Client and click Generate New Refresh Token.
    • Copy this Refresh Token; you’ll use it to get your temporary Access Tokens.

3a. The OAuth flow with curl

OAuth is a two-step process. You don’t send your secret with every report request; instead, you exchange your credentials for a temporary Access Token.

Step A: Exchange Refresh Token for Access Token

Send a POST request to your Workday Token Endpoint.

  • Endpoint: https://YOUR_WORKDAY_HOST/ccx/oauth2/YOUR_TENANT/token
  • Content-Type: application/x-www-form-urlencoded

Replace YOUR_WORKDAY_HOST and YOUR_TENANT with your own. My host is wd2-impl-services1.workday.com, so my token endpoint looks like https://wd2-impl-services1.workday.com/ccx/oauth2/mytenant/token.

cURL Example:

To keep the client secret and refresh token out of your shell history (and out of ps while curl runs), read them into variables with read -s and hand them to curl through a config on stdin (-K -) instead of as command line arguments:

read -rsp "Client ID: " CLIENT_ID; echo
read -rsp "Client secret: " CLIENT_SECRET; echo
read -rsp "Refresh token: " REFRESH_TOKEN; echo

curl "https://YOUR_WORKDAY_HOST/ccx/oauth2/YOUR_TENANT/token" -K - <<EOF
data = "grant_type=refresh_token"
data-urlencode = "refresh_token=$REFRESH_TOKEN"
data-urlencode = "client_id=$CLIENT_ID"
data-urlencode = "client_secret=$CLIENT_SECRET"
EOF

The response will contain an access_token (valid for 60 minutes).

Step B: Request the RaaS Report

Now, use that access_token in the Authorization header of your report URL.

cURL Example:

read -rsp "Access token: " ACCESS_TOKEN; echo

curl "https://YOUR_WORKDAY_HOST/ccx/..." -K - \
  --connect-timeout 60 \
  --max-time 1800 \
  -o ~/Downloads/raas_results.csv <<EOF
header = "Authorization: Bearer $ACCESS_TOKEN"
EOF

3b. The OAuth flow with python

import urllib.request
import urllib.parse
import json
import os
import datetime
import getpass

# --- CONFIGURATION ---
WORKDAY_HOST = "YOUR_WORKDAY_HOST"  # e.g. wd2-impl-services1.workday.com
TENANT = "YOUR_TENANT"
REPORT_URL = "YOUR_RAAS_URL"
NTFY_TOPIC = ""  # Optional ntfy.sh notifications for long running tests

# Secrets come from environment variables, or a prompt if they aren't set,
# so they never live in this file or your shell history.
CLIENT_ID = os.environ.get("WORKDAY_CLIENT_ID") or getpass.getpass("Client ID: ")
CLIENT_SECRET = os.environ.get("WORKDAY_CLIENT_SECRET") or getpass.getpass("Client secret: ")
REFRESH_TOKEN = os.environ.get("WORKDAY_REFRESH_TOKEN") or getpass.getpass("Refresh token: ")


def get_access_token():
    url = f"https://{WORKDAY_HOST}/ccx/oauth2/{TENANT}/token"
    data = urllib.parse.urlencode(
        {
            "grant_type": "refresh_token",
            "refresh_token": REFRESH_TOKEN,
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
        }
    ).encode("utf-8")

    req = urllib.request.Request(url, data=data, method="POST")
    with urllib.request.urlopen(req) as response:
        return json.loads(response.read())["access_token"]


def download_report(token):
    req = urllib.request.Request(REPORT_URL)
    req.add_header("Authorization", f"Bearer {token}")

    timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
    filepath = os.path.expanduser(f"~/Downloads/{timestamp}_oauth_raas.csv")

    # 1800 seconds = 30 minutes
    with urllib.request.urlopen(req, timeout=1800) as response:
        with open(filepath, "wb") as f:
            f.write(response.read())


def send_ntfy(message):
    if NTFY_TOPIC:
        url = f"https://ntfy.sh/{NTFY_TOPIC}"
        req = urllib.request.Request(url, data=message.encode("utf-8"), method="POST")
        urllib.request.urlopen(req)


try:
    print("Refreshing token...")
    token = get_access_token()

    print("Downloading report (this may take a while)...")
    download_report(token)

    print("Success! Sending notification.")
    send_ntfy("Workday Report downloaded successfully to Downloads!")

except Exception as e:
    print(f"Error: {e}")
    send_ntfy(f"Workday Script Failed")