IBM watsonx brings model inference, AI governance and agent orchestration into one platform, so a single IBM Cloud account can hold prompts, deployed models, governance evidence and agents that call business systems with stored credentials. Securing it means getting three layers right: IBM Cloud IAM for the account, workspace collaborator roles for projects, deployment spaces and governance inventories, and the connections and channels through which watsonx Orchestrate agents reach other systems and users. This guide covers those customer-side settings for watsonx.ai, watsonx.governance and watsonx Orchestrate on IBM Cloud, including AI guardrails, activity tracking events and embedded chat security. It is written for platform owners, security architects and AI governance leads in regulated organisations such as banks. Account-wide IBM Cloud controls are in the IBM Cloud Security Guide; this page focuses on watsonx.
This is an independent guide from NHI Mgmt Group, based on IBM's public watsonx documentation as of November 2026. It is not sponsored or reviewed by IBM. Product features change, so confirm settings against IBM's current documentation.
Key takeaways
- Two role systems apply at once. IBM Cloud IAM roles control services and the account, while workspace collaborator roles (Admin, Editor, Viewer) control each project, deployment space or inventory; being an account Administrator does not make you a project Admin.
- Give most users the minimum IAM set. IBM's setup guidance for non-administrative users is Viewer on the resource group, Reader service access and Viewer platform access.
- Review AI guardrail settings per use case. HAP filtering is on by default for natural language models, while PII filtering and Granite Guardian are off until you turn them on.
- Choose member or team credentials deliberately in Orchestrate. Member connections hold per-user credentials, team connections share one credential, and on-behalf-of flows keep tool calls tied to the real user in the live environment.
- Configure embedded chat security before going live. Orchestrate embedded chat validates a JWT signed with your private key on every request; anonymous mode is meant only for public, low-risk use.
How identity and access work in IBM watsonx
IBM describes watsonx security on five levels: network, enterprise, account, data and collaborator. The account level is provided by IBM Cloud: single sign-on, role-based, group-based and service-based access control and user authentication, all managed through IBM Cloud Identity and Access Management (IAM). Users need an IBMid, which is created when they accept an invitation to the account.
| Level | What it controls | Where you configure it | Examples |
|---|---|---|---|
| IAM platform roles | Service instances and account administration | IBM Cloud IAM, Administration > Access (IAM) | Viewer, Operator, Editor, Administrator |
| IAM service roles | Actions inside each service | IBM Cloud IAM | Reader, Manager |
| Workspace collaborator roles | Assets, collaborators and settings in one project, deployment space or catalog | The workspace's access settings, by its Admin | Admin, Editor, Viewer |
| Governance roles | Inventories, AI use cases and factsheets | watsonx.governance inventories and use cases | Inventory Viewer, Editor, Admin/Owner |
| Orchestrate connections | How agents and tools authenticate to external systems | watsonx Orchestrate connections, per draft and live environment | member or team credentials, OAuth, SSO/OBO |
IBM's roles page describes the IAM platform roles: Viewer is the minimum to see watsonx services and allows joining projects and spaces; Operator configures existing service instances; Editor adds provisioning and plan changes; Administrator has the same permissions as the account owner, including adding users and assigning roles. Workspace roles are independent and specific to each workspace. For SSO design across the account, see How Single Sign On Works.
Admin roles and privileged access
IBM's guidance on adding users sets two profiles:
| Profile | Resource group | Service access | Platform access |
|---|---|---|---|
| Non-administrative user (minimum) | Viewer | Reader | Viewer |
| Administrator | As required | Manager for the services in the account | Administrator, plus Administrator on All Account Management Services |
The Administrator platform role grants Manager on all services in the account, so treat it as a privileged role: keep the group small, put it in an access group rather than individual assignments, and review it on a schedule. Users are invited from Administration > Access (IAM) > Users > Invite users, up to 100 addresses at a time with the same policy, and policies take effect when the invitation is accepted. Use access groups for every role profile so joiners and leavers are handled in one place. See the Privileged Access Management Guide for the wider PAM approach.
Workspace and governance roles
- Projects and deployment spaces: Admin controls assets, collaborators and settings; Editor controls assets; Viewer can view. Keep production deployment spaces separate from development projects, with a small Admin group and deployment pipelines running under service IDs.
- Governance inventories: the IAM platform Admin provisions watsonx.governance, creates inventories, enables external model tracking and customises report templates. In an inventory, Viewer views AI use cases and generates reports; Editor also creates and edits use cases, evaluates model deployments and adds collaborators and attachments to a use case; Admin/Owner also adds inventory collaborators, deletes the inventory and updates asset type definitions. An inventory role overrides a use case role.
- Separation of duties: the people who build and deploy models should not be the only Admins of the inventory that records their approval. Give model risk or compliance staff Admin on inventories and builders Editor.
For governance process design, see the AI Model Risk Management Guide.
Integrations, API tokens and service accounts
watsonx.ai and IBM Cloud credentials
Programmatic access to watsonx.ai uses IBM Cloud API keys. Use service IDs with their own API keys for pipelines, applications and scheduled jobs, so automation does not depend on a person's account, and grant each service ID only the IAM roles and workspace membership it needs. Keep keys in a secrets manager, rotate them on a schedule, and remove keys from service IDs that are no longer used. Service IDs and API keys are non-human identities in the full sense; see NHI lifecycle automation.
watsonx Orchestrate connections
In watsonx Orchestrate, a connection represents a dependency on an external system and gives agents, tools, knowledge bases and models what they need to authenticate. IBM's connections documentation lists these authentication kinds:
| Kind | How it works | Use it for |
|---|---|---|
| Basic, Bearer, API key | Credentials passed directly to the consuming tool | Service-to-service APIs with a dedicated, scoped credential |
| OAuth (client credentials, auth code, implicit, password) | Orchestrate authenticates and passes an access_token to the tool | APIs that support OAuth; auth code flows run when users work through the Orchestrate UI |
| SSO/IDP | Identity from the customer's identity provider for embedded web chat | Customer or employee chat on your own site |
SSO/OBO (oauth_auth_on_behalf_of_flow) | Token exchanged on behalf of the signed-in user | Tools that must act with the user's own permissions |
| Key-Value | A secure dictionary for Python tools, local MCP toolkit environment variables and AI Gateway model connections | Team-level settings and model provider credentials |
Each connection is either member (credentials per user) or team (shared credentials); Key-Value is team only. Connections are configured separately for the draft and live environments. IBM's guidance is to use Key-Value connections for draft imports and to reserve SSO/OBO for the live environment, where tool execution has a real user session.
Decision guidance: choose member or OBO connections when different users are entitled to different records, so the target system enforces their permissions. Choose team connections only when every user of the agent may see the same data, and then scope the shared credential to exactly what the agent needs. With the Agent Development Kit CLI, keep secrets in environment variables and pass them to orchestrate connections set-credentials so they stay out of shell history and source control.
Agents, collaborators and MCP toolkits
Orchestrate agents can list other agents as collaborators, and toolkits can bring MCP servers in as local or remote tools. Review collaborator chains like delegation: an agent with read-only tools should not be able to route a request to a collaborator holding write credentials unless that is intended. Import only MCP toolkits from sources you trust and give each its own connection. See the MCP Security Guide.
Embedded chat security
For Orchestrate embedded chat, IBM documents that security is enabled at the instance level by default but becomes active only after you register your keys, and the chat does not work until that is done. Your client application key pair signs a JWT for every request, and Orchestrate validates it with your uploaded public key. An optional IBM key pair encrypts a user_payload carrying an sso_token for the OBO flow. Refresh tokens during a session with updateIdentityToken(). To rotate keys, IBM describes disabling and re-enabling security with new keys, so plan rotation in a maintenance window. With security disabled, anonymous access is allowed; IBM limits that mode to public demos, anonymous chat or low-risk environments and advises confirming that no tools hold credentials for protected systems first.
Guardrails and data controls
watsonx.ai AI guardrails screen foundation model input and output:
| Filter | Detects | Applies to | Default | Threshold |
|---|---|---|---|---|
| HAP | Hate, abuse and profanity | Input and output, set separately | On for natural language models | Adjustable 0.0 to 1.0 (1 disables) |
| PII | Personal data such as phone numbers and email addresses | Input and output, set separately | Off until switched on | Fixed at 0.8 |
| Granite Guardian | Social bias, jailbreaking, violence, profanity, unethical behaviour, harm engagement, evasiveness, groundedness, context and answer relevance, function-calling hallucination | User input | Off until switched on | Adjustable 0.0 to 1.0 (1 disables) |
Guardrails are set in Prompt Lab through the AI guardrails settings, or through the moderations field of the text generation REST API and the Python SDK. As of November 2026 IBM's docs describe detection for English text and natural language models, so add your own screening where prompts arrive in other languages or target code models. Decide per use case which filters are mandatory and record that decision in the governance inventory. See the AI Guardrails and AI Firewalls Guide.
At the network level, IBM documents the IBM Cloud setting to allow specific IP addresses for the console and watsonx (per user or account), the Administration > Cloud integrations > Firewall configuration for watsonx.ai Studio CIDR ranges, inbound firewall rules for private data sources, and Satellite Connector or a Satellite location for reaching on-premises data (Satellite Connector replaces the deprecated Secure Gateway). Data is stored in an IBM Cloud Object Storage instance with encryption at rest and in motion; IBM's enterprise level also recommends separate accounts for development, testing and production.
Logging and detection
watsonx sends events to IBM Cloud Activity Tracker Event Routing, which you configure in the IBM Cloud account. Service events appear in the region where the service is provisioned; account, user management and global platform events appear in the region chosen when Event Routing was configured. Event categories include watsonx.ai Studio projects and connections, watsonx.ai Runtime deployments, jobs, instances and training, foundation model inferencing and tokenisation, watsonx.governance APIs, and IAM and user management.
| Watch for | Example event action | Why |
|---|---|---|
| New or changed production deployments | pm-20.deployment.create, pm-20.deployment.update | Unreviewed model changes in a governed space |
| Deployment deletion | pm-20.deployment.delete | Service disruption or evidence loss |
| Project creation and deletion | data-science-experience.project.create, data-science-experience.project.delete | Shadow workspaces outside governance |
| Inference volume by identity | pm-20.foundation-model.send | Leaked API keys or misuse show up as unusual volume |
| IAM and user changes | Account and user management events | New Administrators, API keys or access group changes |
Metrics: number of users with the Administrator platform role (trend down to a named group); share of production deployment spaces whose deployers are service IDs; share of generative AI use cases with a recorded guardrail decision in the inventory; API keys older than your rotation period (target zero); Orchestrate team connections reviewed in the last quarter; and embedded chat instances running with security active (target 100 percent).
Hardening baseline
- Structure accounts: separate IBM Cloud accounts or at least resource groups for development, test and production, as IBM's enterprise level recommends.
- Set up access groups: minimum user profile (Viewer, Reader, Viewer), a small administrator group, and governance roles; turn on SSO for the account.
- Restrict network access: allow specific IP addresses for the console and watsonx where your users have fixed egress, and use Satellite Connector for private data.
- Move automation to service IDs: create service IDs per pipeline and application, store keys in a secrets manager and remove personal keys from automation.
- Govern use cases: create inventories, assign Admin to risk owners and Editor to builders, and require a use case before production deployment.
- Configure guardrails: turn on PII filtering and Granite Guardian where the use case needs them, tune HAP thresholds in a test project first, and record the decision.
- Secure Orchestrate: member or OBO connections for user-specific data, scoped team connections otherwise, embedded chat security active, collaborator chains reviewed.
- Turn on Event Routing and build the alerts above. Test each step in a non-production account; roll back role changes by restoring the previous access group policy.
| Control | NIST SP 800-53 Rev. 5 | NIST CSF 2.0 | ISO/IEC 42001 and OWASP |
|---|---|---|---|
| Access groups, minimum roles, small Administrator group | AC-2, AC-6 | PR.AA-05 | OWASP LLM06 Excessive Agency |
| Service IDs and API key rotation | IA-5 | PR.AA-05 | OWASP LLM02 Sensitive Information Disclosure |
| Member and OBO connections | AC-3, AC-6 | PR.AA-05 | OWASP LLM06 |
| AI guardrails (HAP, PII, Granite Guardian) | SI-10 | PR.DS-01 | OWASP LLM01 Prompt Injection, LLM02 |
| Governance inventories and use cases | PM-9 | GV.RM-01 | ISO/IEC 42001 AI management system |
| Activity Tracker Event Routing | AU-2, AU-12, SI-4 | DE.CM-09 | OWASP LLM10 Unbounded Consumption |
Common misconfigurations
- Administrator as the default role: data scientists given the Administrator platform role to unblock a project, which also grants Manager on every service in the account.
- Personal API keys in pipelines: deployment jobs that stop when the key owner leaves and cannot be attributed to a system.
- Guardrails assumed on: teams expect PII filtering because HAP is on by default, when PII and Granite Guardian need to be switched on.
- Team connection for user data: an Orchestrate agent uses one shared credential to reach an HR or banking system, so every chat user can retrieve any record the credential can read.
- Embedded chat in anonymous mode: security disabled for a pilot and left that way while tools hold credentials for internal systems.
- No Event Routing: watsonx events not routed in the account, so deployment changes and inference spikes leave no reviewable trail.
Practitioner checklist
- Assign IAM roles only through access groups, with Viewer, Reader and Viewer as the user default.
- Keep the Administrator platform role to a small named group and review it quarterly.
- Separate development, test and production accounts or resource groups and deployment spaces.
- Run all automation with service IDs whose keys live in a secrets manager and rotate on schedule.
- Give governance inventory Admin to risk owners and Editor to builders.
- Record a guardrail decision per use case and switch on PII and Granite Guardian where required.
- Use member or OBO connections for user-specific data in Orchestrate and scope team credentials tightly.
- Activate embedded chat security with your key pair before any production launch.
- Configure Activity Tracker Event Routing and alert on deployment, project and IAM changes.
Standards and references
- IBM: Security for IBM watsonx on IBM Cloud
- IBM: Levels of user access roles in IBM watsonx
- IBM: Add users to the account
- IBM: Collaboration roles for governance
- IBM: Filtering foundation model content with AI guardrails
- IBM: IBM Cloud Activity Tracker Event Routing events for watsonx
- IBM watsonx Orchestrate: Connections overview
- IBM watsonx Orchestrate: Securing the embedded chat
Related NHI Mgmt Group resources: IBM Cloud Security Guide, AI Governance Guide, Agent Identity and Access Guide, Securing Agent Frameworks Guide.