Skip to content
KiweelyKiweelyKiweely

Resolving “Tenant mapping not found (OP-4008)”, EU vs. US Regional Base URL 401 Errors, and client_secret_basic in Workday Extend OAuth 2.0

Connecting an external system to Workday Extend APIs via OAuth 2.0 Client Credentials can fail with OP-4008 (Tenant mapping not found) or 401 Unauthorized. Learn how to configure Create Client Credentials Mapping, select the right regional API Gateway URL, and enforce client_secret_basic.

  • Checked against Workday on
  • Applies to Workday Extend
  • 4 min read
  • Published
  • By Kiweely
On this page

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:

json
{
  "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

  1. 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).
  2. 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.
  3. Run Create Client Credentials Mapping in 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.
  4. Include tenant_alias in the x-www-form-urlencoded Request Body:
    • When calling the token endpoint (POST /oauth2/v1/token), pass both grant_type=client_credentials and tenant_alias=<your_tenant_alias> in the application/x-www-form-urlencoded body.

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:

http
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_dpt1

Workarounds When the Third-Party Caller Only Supports client_secret_post

If the external application cannot be configured to send client_secret_basic headers:

  1. 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.
  2. 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

  1. 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.
  2. Check your Developer Site Profile to confirm whether the tenant’s account uses the us, eu, uk, or sg regional gateway URL.
  3. Execute a POST request to <regional_gateway>/oauth2/v1/token using Authorization: Basic <Base64(Client_ID:Client_Secret)> and grant_type=client_credentials&tenant_alias=<tenant>, confirming that Workday returns HTTP 200 OK with a bearer access token, and use that token to GET or POST records on /apps/<appId>/v1/<businessObject>.

Sources checked

Related guides

All guides

Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.

We’ll email you once to confirm. Unsubscribe in one click from any issue.