Fixing 400 Bad Request: "Tenant mapping not found (OP-4008)" on OAuth 2.0 Client Credentials
When an external application or integration middleware calls the Workday Cloud Platform OAuth 2.0 token endpoint (/oauth2/v1/token) using the Client Credentials grant type (grant_type=client_credentials) to write or read Workday Extend Model Business Object APIs, the gateway may reject the request with HTTP 400 Bad Request and error code OP-4008:
{
"error": "Tenant mapping not found (Error ID: 817891)",
"status": 400,
"errors": [
{
"code": "OP-4008",
"title": "Tenant mapping not found"
}
]
}Root Cause of OP-4008
Registering an API Client on the Workday Developer Site (or adding an Integration System User via App Manager > Add Integration User for Simplified ISU authentication inside the app) and creating an External Client CredStore (which is only used when Workday calls outbound to third-party APIs) does not automatically map an inbound OAuth 2.0 Client Credentials request to a specific tenant and Integration System User (ISU).
When an external system authenticates inbound with grant_type=client_credentials, the Workday Extend Authorization Service must look up which tenant and which ISU serve as the subject of the issued access token. If either the tenant mapping task in Workday or the tenant_alias form parameter in the token request is missing or mismatched, the gateway returns OP-4008.
Step-by-Step Fix in the Workday Tenant and Token Request
- Create the Integration System User (
ISU): Run the Create Integration System User task in the target Workday tenant and assign the ISU to an Integration System Security Group (ISSG) that has View and Modify permissions on your Extend App’s security domain (followed by Activate Pending Security Policy Changes). - Register the API Client on the Workday Developer Site: Under the customer account on the Developer Site, register the API Client with the required Extend App scopes and authorize the target non-development or development tenant.
- Run
Create Client Credentials Mappingin the Tenant:- In the target Workday tenant, run the Create Client Credentials Mapping task (secured by the Integration Security domain in the Integration functional area).
- Enter the exact Client ID from the Workday Developer Site Console.
- Select the Integration System User created in Step 1.
- Include
tenant_aliasin thex-www-form-urlencodedRequest Body:- When calling the token endpoint (
POST /oauth2/v1/token), pass bothgrant_type=client_credentialsandtenant_alias=<your_tenant_alias>in theapplication/x-www-form-urlencodedbody.
- When calling the token endpoint (
Resolving 401 Invalid Credentials Caused by EU vs. US Regional API Gateway Base URLs
Even when your Client ID, Client Secret, and Create Client Credentials Mapping are valid, calling https://api.us.wcp.workday.com/oauth2/v1/token (or https://api.workday.com) for a customer tenant hosted in a European, UK, or Asia-Pacific data center fails with 401 Unauthorized / Invalid Credentials.
Every Workday Extend enterprise account is bound to a specific regional API Gateway and Authorization Base URL. You cannot authenticate an EU-hosted customer account against the US API Gateway:
| Region | API Gateway Base URL | Authorization Base URL |
|---|---|---|
| RegionUnited States | API Gateway Base URLhttps://api.workday.com or https://api.us.wcp.workday.com |
Authorization Base URLhttps://auth.api.workday.com or https://api.us.wcp.workday.com/auth |
| RegionGermany (EU) | API Gateway Base URLhttps://api.eu.wcp.workday.com |
Authorization Base URLhttps://api.eu.wcp.workday.com/auth |
| RegionUnited Kingdom | API Gateway Base URLhttps://api.uk.wcp.workday.com |
Authorization Base URLhttps://api.uk.wcp.workday.com/auth |
| RegionSingapore | API Gateway Base URLhttps://api.sg.wcp.workday.com |
Authorization Base URLhttps://api.sg.wcp.workday.com/auth |
| RegionPersonal Dev Accounts | API Gateway Base URLhttps://api.odp.wcp.workday.com |
Authorization Base URLhttps://api.odp.wcp.workday.com/auth |
To verify which regional gateway a customer account uses, open your Profile on the Workday Developer Site (https://developer.workday.com/profile), where the assigned API Gateway URL is listed alongside each account. Use that exact regional host for both the OAuth 2.0 token request (https://api.eu.wcp.workday.com/oauth2/v1/token) and all subsequent Extend REST API calls (https://api.eu.wcp.workday.com/apps/<appId>/v1/...).
Why client_secret_post Fails with 401 Unauthorized (Enforcing client_secret_basic)
Many third-party integration platforms (and standard Workday Integration API Clients registered via Register API Client for Integrations) default to sending OAuth client credentials in the HTTP POST request body (client_secret_post).
However, Workday Extend API Clients strictly require client_secret_basic. If a third-party caller sends the Client ID and Client Secret in the application/x-www-form-urlencoded body instead of an Authorization header, the Workday Extend token endpoint returns 401 Unauthorized.
Formatting the Authorization Header for Workday Extend Token Requests
Encode <Client_ID>:<Client_Secret> (with no space after the colon) using Base64 and pass it in the HTTP Authorization header, while keeping only grant_type and tenant_alias in the URL-encoded form body:
POST /oauth2/v1/token HTTP/1.1
Host: api.eu.wcp.workday.com
Authorization: Basic <Base64(Client_ID:Client_Secret)>
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&tenant_alias=customer_tenant_dpt1Workarounds When the Third-Party Caller Only Supports client_secret_post
If the external application cannot be configured to send client_secret_basic headers:
- API Gateway / Middleware Transformation: Route the token request through your organization’s API Gateway (such as AWS API Gateway, Azure API Management, or MuleSoft) to extract the credentials from the POST body and inject the
Authorization: Basic ...header before forwarding to Workday. - Read-Only WQL via Standard Integration API Client: If the third-party application only needs to read data from your Workday Extend Business Object, register a standard Workday Integration API Client in the tenant (Register API Client for Integrations), which natively supports
client_secret_post, and query the Extend Business Object’s data source via the WQL REST API (/wql/v1/data).
How to Verify in the Tenant
- Run View Client Credentials Mappings in your Workday tenant and confirm that your Developer Site API Client’s Client ID is mapped to the active Integration System User.
- Check your Developer Site Profile to confirm whether the tenant’s account uses the
us,eu,uk, orsgregional gateway URL. - Execute a
POSTrequest to<regional_gateway>/oauth2/v1/tokenusingAuthorization: Basic <Base64(Client_ID:Client_Secret)>andgrant_type=client_credentials&tenant_alias=<tenant>, confirming that Workday returns HTTP200 OKwith a bearer access token, and use that token toGETorPOSTrecords on/apps/<appId>/v1/<businessObject>.