Managing app connections and credentials

To integrate external applications with IBM watsonx Orchestrate, you must first establish a secure connection. This connection serves as a bridge for communication between watsonx Orchestrate and the external app. You can manage the connections and their associated credentials using supported authentication methods such as API keys, OAuth, or other protocols ensuring secure and flexible integration.

Managing connections

The connection settings page is your central hub for managing all app connections. From here, you can:

Access connection settings to view all connections
Add new connections by specifying details such as ID, display name, authentication type, and credential type
Filter connections based on environment status or authentication method
Edit existing connections to update credentials or configuration

The following diagram illustrates the key actions you can perform on the connection settings page:

Accessing connection settings

To manage your app connections and credentials:

From the main menu, select Manage > Connections.
You see a list of all your configured connections.
The Connection settings page opens, where you can manage both connections and credentials:
1. Connections: You can add and configure connections to integrate with your applications.
2. Credentials: You can view and manage your saved credentials (personal or shared) for use in both draft and live environments.

Adding a new connection

You can create connections in both draft and live environments. The draft environment is intended for testing and staging, while the live environment reflects production-ready configurations. This dual setup ensures you can validate integrations safely before deploying them to production.

To add a new connection:

On the Connection settings page, click Add new connection.
Under Define connection details, enter a Connection ID and Display name.
Click Save and continue.
Configure draft connection:
- By default, Single sign-on (SSO) is turned off. To enable it, refer to Configuring single sign-on for applications.
- Choose an Authentication type and specify the required parameters
- Set the Credential type
  - Note: After setting team credentials, click Connect to activate access for all team members.
- Click Next
Configure live connection:
- Either Paste draft configuration or define a new setup.
  
  Note: You can paste the draft configuration to the live environment only for the following authentication types: API Key, Basic Auth, Bearer Token, and OAuth. For OAuth, the supported grant types are authorization code, client credentials, implicit, password, and on behalf of flow.
  The Key Value credential type is not supported for draft-to-live pasting. You must manually enter the values in the live configuration.
- Click Reset to clear all fields if needed
Click Add connection.

Note: The icon A Supports appears.

indicates that the connection was successfully established.

Dynamic authentication setup

IBM watsonx Orchestrate automatically identifies the right authentication type from a tool’s metadata (such as its OpenAPI specification). This feature helps you set up connections faster by showing only the required fields and pre-filling standard values when available, reducing manual effort and errors.

Dynamic authentication configuration works by displaying only the fields relevant to the detected authentication type. It automatically fills standard values, such as server_url and token_url, when these are available in the OpenAPI specification. You must enter sensitive credentials manually because they are never auto-filled for security.

Supported auto-fill fields by authentication type

Use the following table to know which fields are auto-populated for each supported authentication type:

Auth type	Auto-populated fields
`basic_auth`	`server_url`
`apiKey`	`server_url`, `api_key_location`
`oauth2client`	`scope`, `token_url`, `server_url`
`oauth2password`	`scope`, `token_url`, `server_url`
`oauth2_code`	`scope`, `token_url`, `server_url`, `auth_url`

Information:

Connection name and Connection Id are auto-suggested, but you can modify them before proceeding.
watsonx Orchestrate does not auto-fill custom auth types. This includes keyvalue pair and SSO-related flows such as on_behalf_of_flow and token_exchange.
No custom fields from the spec (other than standard fields listed above) are auto-populated.
You must enter client_id and client_secret manually because they are never auto-populated.

Filtering connections

To help you quickly locate specific connections, use the available filters on the Connection settings page. You can filter connections based on:

Draft connection status - whether the draft configuration is active or inactive.
Live connection status - whether the live configuration is active or inactive.
Authentication type - used in either the draft or live environment.

Editing a connection

You can update an existing connection at any time to reflect changes in configuration or credentials.

On the Connection settings page, click the edit icon next to the app.
Click Edit.
Make changes in the Draft and Live tabs.
Click Save to apply updates.

Authentication types

Authentication types define how watsonx Orchestrate verifies and grants access to an external app. Choosing the right authentication method is essential for ensuring secure and seamless communication between watsonx Orchestrate and the external app.

Specify the authentication type while adding a new connection. Refer Overview of authentication types for a detailed explanation of each authentication type.

Credential types

When connecting apps to watsonx Orchestrate, you need to define how the credentials are managed. This ensures secure access to external applications and services. There are two types of credentials you can assign to an app:

1. Member credentials

Member credentials are user-specific. Each user provides their own credentials for the app, which are stored securely and used only for that individual’s interactions.

These credentials are private and not shared with other users.
It can be used when access to the app is tied to individual user accounts or when personalized data access is required.

Note: If you have selected "Member credentials" and haven't provided the details, watsonx Orchestrate prompts you to enter them through the chat interface the first time you use the tool. The credentials are securely saved and accessible for subsequent tool invocations.

2. Team credentials

Team credentials are shared across all users in a team. These are typically managed by an admin and are useful when all users can access the app using the same credentials.

Simplifies credential management.
Ensures consistent access across the team.
Best suited for shared services or team-wide integrations.

Note: After setting team credentials, click Connect to activate access for all team members.

Credential parameters by authentication type

The credential parameters vary depending on the authentication type used:

Authentication Type	Required Parameters
API Key	API key
Basic Authentication	Username and password
Bearer Token	Bearer token
Key-Value Pair	Key and value
OAuth2 Authorization Code	Server URL, token URL, authorization URL, client ID, client secret
OAuth2 Client Credentials	Server URL, token URL, authorization URL, client ID, client secret, grant type
OAuth2 Password	Username and password

What to do next

Now, that your app connection is set up, the next step is to add credentials so the connection can authenticate securely. To learn how to add, edit, or manage credentials, Configuring app credentials for more details