🧐This blog is written specifically for IBM Planning Analytics on IBM Cloud (PAonCloud). If you are running PA on TechZone, on-premises, or in a self-managed cloud environment (sometimes called PAaaS), the OAuth URL structure and tenant-identity patterns are different — please check the resources available on Seismic and the IBM Planning Analytics documentation.
Why does this matter?
Imagine asking your AI agent: "What was our Q3 revenue variance against budget?" — and getting a live, accurate answer pulled directly from Planning Analytics, not a stale spreadsheet export.
That's the promise of connecting Planning Analytics to watsonx Orchestrate. But making it work securely isn't trivial. PA needs to know who is asking, not just what is being asked. That means we need OAuth — the industry standard for delegated authorisation — so that each user's PA identity flows through to every agent tool call.
This blog walks you through every step: registering the OAuth client in PAonCloud, wiring up the connection in wxOrchestrate, completing the interactive authorisation flow, and finally associating the connection to a real MCP tool. No hand-waving — just the exact commands and values you need, tested against PA on IBM Cloud.
---
Before you start: Understand the cast of characters
There are two systems involved, and they play very different roles in the OAuth dance:
| Role |
System |
What it does |
| OAuth Authorization Server |
IBM Planning Analytics Workspace |
Issues tokens after a user logs in |
| OAuth Client |
IBM watsonx Orchestrate |
Requests tokens on behalf of the user |
```
┌──────────────────────────────────────────────────────────────────────┐
│ PA Workspace (OAuth Server) │
│ generates ──▶ Client ID + Client Secret ──fed into──▶ wxO │
│ receives ◀── Redirect URL ◀──registered── wxO │
└──────────────────────────────────────────────────────────────────────┘
```
One critical constraint to keep in mind: Both PA and wxO require a real user to be present during the OAuth flow. Headless / client-credentials flows are not supported by PA. The connection only works when users interact via the wxOrchestrate integrated web chat UI.
---
⚠️ PA on IBM Cloud vs other PA deployment types
This is the single most common source of confusion when setting up this integration. The behaviour is meaningfully different depending on where your PA instance is running.
| Deployment type |
Tenant identity in OAuth |
Query parameters? |
| IBM Cloud — PAonCloud (this blog) |
Encoded in the **hostname**: `<your-tenant>-dev.planning-analytics.cloud.ibm.com` |
❌ No `?tenantId=` needed |
| TechZone / on-premises / PAaaS |
Passed as **query parameters** on the base host URL |
✅ `?accountId=<ID>&tenantId=<ID>` required |
If you have previously set up OAuth with a TechZone or PAaaS instance and are used to appending `?accountId=...&tenantId=...` to your OAuth URLs — **stop**. On IBM Cloud, each tenant has its own subdomain, so the tenant identity is already encoded in the hostname. Adding query parameters will break the flow.
Similarly, the MCP endpoint URL path differs between deployment types (more on this in Step 5).
Throughout this guide, all URL examples are for PA on IBM Cloud.
---
The OAuth endpoint map (PA on IBM Cloud)
Let's assume we have a development and production environment in our instance of Planning Analytics on IBM Cloud. We need to note the following URLs.
| Endpoint |
URL |
| Authorization URL (dev) |
`https://<your-tenant>-dev.planning-analytics.cloud.ibm.com/oauth2/authorize` |
| Token URL (dev) |
`https://<your-tenant>-dev.planning-analytics.cloud.ibm.com/oauth2/token` |
| Authorization URL (prod) |
`https://<your-tenant>.planning-analytics.cloud.ibm.com/oauth2/authorize` |
| Token URL (prod) |
`https://<your-tenant>.planning-analytics.cloud.ibm.com/oauth2/token` |
| Required scope |
`v0userContext` — the only scope PA accepts |
| wxO redirect / callback URL |
`https://<wxo-region>.watson-orchestrate.cloud.ibm.com/mfe_connectors/api/v1/agentic/oauth/_callback` |
---
Step 1 — Get the wxO callback URL (start here, not in PA)
It's tempting to open PA first. Don't. You need the wxOrchestrate redirect URL *before* you can register anything in PA — PA's OAuth client form asks for it upfront, and any typo means deleting the client and starting over.
In the wxOrchestrate UI:
1. Navigate to the Connections section and begin creating a new OAuth connection.
2. On the connection setup page, you will see a redirect URL in the form:
```
https://<wxo-region>.watson-orchestrate.cloud.ibm.com/mfe_connectors/api/v1/agentic/oauth/_callback
```
3. Copy this URL exactly. PA does exact-string matching on redirect URLs — a trailing slash difference or any whitespace will cause authorisation to fail.
4. Keep the wxO connection page open (or paste the URL into a notes file). You'll come back here in Step 3.
---
Step 2 — Register wxOrchestrate as an OAuth client in PA
Now that you have the callback URL, head over to Planning Analytics Workspace.
1. Log in to PA Workspace as an administrator.
2. Go to Administration → click the Integrations tile → locate OAuth in the list.
3. Click Add.
⚠️PA on IBM Cloud allows only one OAuth client at a time. If a client already exists, click the Action icon → Delete before proceeding. This is a platform constraint, not a misconfiguration.
4. Fill in the form:
| Field |
Value |
| Client name |
`watsonx-orchestrate` (any descriptive label works) |
| Redirect URLs |
Paste the URL you copied from wxO in Step 1 — character for character |
5. Click Generate secret.
6. ⚠️ Copy both values immediately — they are shown exactly once:
| Value |
Where it goes |
| Client ID |
`--client-id` in the wxO connection credentials command |
| Client secret |
`--client-secret` in the wxO connection credentials command |
7. Store both in a password manager or secrets vault before clicking Done.
---
Step 3 — Create and configure the connection in wxOrchestrate
With your Client ID and Client Secret in hand, return to wxOrchestrate. You have two paths: UI or ADK CLI — both reach the same result.
Path A — wxO UI
In the connection setup page you left open in Step 1, fill in:
- Type: `oauth_auth_code_flow`
- Server URL: `https://<your-tenant>-dev.planning-analytics.cloud.ibm.com`
- Authorization URL: `https://<your-tenant>-dev.planning-analytics.cloud.ibm.com/oauth2/authorize`
- Scope: `v0userContext`
- Credentials type: `member`
- Client ID / Client Secret: the values you copied in Step 2
Repeat for the live environment (same values, drop the `-dev` suffix from the URLs).
Path B — ADK CLI
If you prefer a terminal and have the wxOrchestrate ADK installed and authenticated, run the following commands.
Register the connection name:
```bash
orchestrate connections add -a planning_analytics_oauth
```
Configure authentication type and server URL for both environments:
```bash
# Draft (dev) environment
orchestrate connections configure \
-a planning_analytics_oauth \
--env draft \
--type member \
--kind oauth_auth_code_flow \
--server-url https://<your-tenant>-dev.planning-analytics.cloud.ibm.com
# Live (prod) environment
orchestrate connections configure \
-a planning_analytics_oauth \
--env live \
--type member \
--kind oauth_auth_code_flow \
--server-url https://<your-tenant>.planning-analytics.cloud.ibm.com
```
🧐 Why `--type member`?** This tells wxO that each user provides their own PA credentials interactively. PA on IBM Cloud does not support shared team credentials — every user must authenticate with their own IBM ID.
Set the OAuth credentials — replace `<CLIENT_ID>` and `<CLIENT_SECRET>` with the values from Step 2:
```bash
# Draft (dev) environment
orchestrate connections set-credentials \
-a planning_analytics_oauth \
--env draft \
--client-id '<CLIENT_ID>' \
--client-secret '<CLIENT_SECRET>' \
--authorization-url 'https://<your-tenant>-dev.planning-analytics.cloud.ibm.com/oauth2/authorize' \
--token-url 'https://<your-tenant>-dev.planning-analytics.cloud.ibm.com/oauth2/token' \
--scope v0userContext
# Live (prod) environment
orchestrate connections set-credentials \
-a planning_analytics_oauth \
--env live \
--client-id '<CLIENT_ID>' \
--client-secret '<CLIENT_SECRET>' \
--authorization-url 'https://<your-tenant>.planning-analytics.cloud.ibm.com/oauth2/authorize' \
--token-url 'https://<your-tenant>.planning-analytics.cloud.ibm.com/oauth2/token' \
--scope v0userContext
```
👉Alternative — YAML import: If you manage connections as code, define the connection structure in a YAML file and import it:
Create a YAML file in your project folder:
```yaml
# connections/planning_analytics_oauth.yaml
spec_version: v1
kind: connection
app_id: planning_analytics_oauth
environments:
draft:
kind: oauth_auth_code_flow
type: member
server_url: https://<your-tenant>-dev.planning-analytics.cloud.ibm.com
live:
kind: oauth_auth_code_flow
type: member
server_url: https://<your-tenant>.planning-analytics.cloud.ibm.com
```
and then import the connection through the CLI
```bash
orchestrate connections import -f connections/planning_analytics_oauth.yaml
```
Then run the set-credentials commands above to add the secrets — they cannot go in the YAML file
---
Step 4 — Complete the interactive authorisation (each user does this once)
This is the step that makes OAuth meaningful. The connection is configured at the system level, but each individual user must authorise it against their own PA identity. This is by design — it ensures that every agent tool call carries the correct user's permissions.
1. Open the wxOrchestrate web UI (the integrated UI — not an embedded webchat widget). Navigate to Settings → Member Connections.
2. You will see a prompt to connect to Planning Analytics Workspace. Click it.
3. A browser pop-up opens to:
```
https://<your-tenant>-dev.planning-analytics.cloud.ibm.com/oauth2/authorize
```
4. Log in with your PA Workspace credentials — the IBM ID associated with this PA on IBM Cloud tenant.
Your PA access level flows through to every agent call. Admin accounts get full access to all cubes and data; analyst accounts are limited to the cubes your PA administrator has permitted. The OAuth token carries your permissions through to every tool invocation.
5. After a successful login, PA redirects back to the wxO callback URL:
```
https://<wxo-region>.watson-orchestrate.cloud.ibm.com/mfe_connectors/api/v1/agentic/oauth/_callback
```
wxOrchestrate captures the authorisation code and exchanges it for an access token at the PA token URL — all behind the scenes.
6. The connection status changes to Authorized / Connected in the wxO Connections UI:
---
Step 5 — Associate the connection to an MCP tool
The connection is live — now let's put it to work. Create a test agent in wxOrchestrate, add tools through an MCP server, and select the `planning_analytics_oauth` connection you just set up.
⚠️ The MCP endpoint URL — PA on IBM Cloud vs other deployments
This is another point where PA on IBM Cloud diverges from TechZone / PAaaS. When you are prompted for the Universal MCP Endpoint URL, there is a known discrepancy between the IBM Documentation and what PA on IBM Cloud actually expects.
```
https://<PAW_HOST>/api/<PAW_TENANT_ID>/v0/agentic-ai/ibm-pa-tools/mcp
```
This format — with the Tenant ID embedded in the path — applies to TechZone and PAaaS deployments, where multiple tenants share a host and the tenant must be identified explicitly in the API path.
For PA on IBM Cloud, the Tenant ID must be omitted from the path because the tenant is already identified by the hostname:
```
https://<PAW_HOST>/api/v0/agentic-ai/ibm-pa-tools/mcp
```
Use the second format for PA on IBM Cloud. Using the first format (with the tenant ID in the path) will result in a 404 or authentication failure.
Confirming it worked
After associating the connection, you should see the full list of available PA MCP tools loaded in the global workspace:
---
Quick-reference checklist
Use this as your go / no-go gate before testing with an agent.
Start in wxOrchestrate
- [ ] wxO OAuth callback URL confirmed and copied: `https://<wxo-region>.watson-orchestrate.cloud.ibm.com/mfe_connectors/api/v1/agentic/oauth/_callback`
In Planning Analytics — Step 2 (PA on IBM Cloud)
- [ ] Any existing PA OAuth client deleted (only one allowed at a time)
- [ ] New OAuth client created with a descriptive name (e.g. `watsonx-orchestrate`)
- [ ] Redirect URL added — exact copy from the wxO connection setup page (no trailing slash differences)
- [ ] Client ID copied and stored securely
- [ ] Client secret copied and stored securely (shown only once)
Back in wxOrchestrate — Steps 3–4
- [ ] Connection `planning_analytics_oauth` added
- [ ] Connection configured for `draft` and `live` with `kind: oauth_auth_code_flow`, `type: member`
- [ ] Credentials set: `client-id`, `client-secret`, `authorization-url`, `token-url`, `scope v0userContext`
- [ ] OAuth URLs use the hostname-only format (no `?tenantId=` query parameters) — PA on IBM Cloud
- [ ] Interactive authorisation completed in the wxO web chat UI (every user must do this once)
- [ ] Connection shows as Authorized in the wxO Connections UI
End-to-end validation — Step 5
- [ ] MCP endpoint URL used: `https://<PAW_HOST>/api/v0/agentic-ai/ibm-pa-tools/mcp` (no tenant ID in path — PA on IBM Cloud)
- [ ] PA MCP tools visible in the wxO global workspace tool list
- [ ] Test agent call from the wxO web chat returns PA data (not a 401)
---
What's next?
With the OAuth connection in place and PA MCP tools loaded, your agents can now query live Planning Analytics data under the user's own identity. From here you can:
- Build richer prompts — chain PA tools with other wxO tools to answer complex financial questions in natural language.
- Add a dedicated PA agent — use wxO's multi-agent orchestration to route data-heavy planning questions to a specialised PA agent while other intents are handled elsewhere.
- Set up for production — repeat Steps 2–4 against your production PA host (drop the `-dev` suffix) and configure the `live` environment in wxO with the production credentials.
Happy building --and, if in trouble, ask Bob for help!