Connections are composed of 3 parts:

Application ID (app_id): A unique identifier that distinguishes the connection within your environment.
Environment-specific configuration: Define separate configurations for the draft and live states of an agent. Each configuration specifies:

The type of credentials used (for example, Basic Auth, Bearer Token, API Key)
Whether the credentials are scoped to individual users (member) or shared across the organization (team)

Credentials:

For team connections, builders set the credentials, and all users share them across the instance.
For member connections, users are prompted in the chat to enter their credentials if they haven’t already provided them.

Adding and configuring connections

You can add and configure connections in two ways:

Use a combination of the connections add and connections configure commands to define and set up connections manually.
Import connections from a YAML file, just like other watsonx Orchestrate resources.

Importing from a file
Using the CLI only

You can create and import connection configurations using YAML files, which makes it easier to share setup details across users. However, you must set credentials separately using the CLI. This requirement helps prevent storing sensitive information like passwords in unsecured files.In your YAML specification file, define the connection’s structure, including:

Application ID (app_id)
Authentication type
Environment-specific settings (e.g., draft vs. live)
Credential scope (member or team)

YAML

spec_version: v1
kind: connection
app_id: my_app
environments:
    draft:  # in draft each person needs to provide their own basic credentials
        kind: basic
        type: team
        server_url: https://example.com/
    live:
        kind: api_key # note it's possible to auth different in the deployed live agent vs the draft agent
        type: member
        server_url: https://example.com/

Show detailed flag descriptions

enum

Defines the schema version of the file. The ADK uses this value to manage in-place upgrades or display warnings when breaking changes prevent an upgrade. Possible Values: v1

enum

Specifies the type of configuration. For connection configurations, this value is always connection. Possible Values: connection

string

The unique name of the application this connection integrates with (e.g., box, tavily, github). Use only alphanumeric characters and underscores.

object

The configuration of each of the draft and live environments.

Hide properties

object

The configuration of the draft environment.

Hide properties

enum

The kind of credentials to use for the connection in this environment, note this can differ per environment.Possible values: basic, bearer, api_key, oauth_auth_code_flow, oauth_auth_implicit_flow, oauth_auth_password_flow, oauth_auth_client_credentials_flow, oauth_auth_on_behalf_of_flow, key_value

enum

Whether these credentials for the connection in this environment should be shared by all users (team), or provided by each user (member).Possible values: team, member

string

The base URL of the server this application is associated with (if any). In the case of oauth connections, this may differ from the token URL which is provided via the credentials themselves.

boolean

default:false

Only set to true for oauth_auth_on_behalf_of_flow connections. When this is true, the connection will be done through an Identity Provider (IDP).

object

To configure headers and body parameters to an IDP provider when the connection type is oauth_auth_on_behalf_of_flow.

Show properties

object

A set of key value pairs to send as headers to the upstream IDP provider.

object

A set of key value pairs to send as the body to the upstream IDP provider.

object

A collection of headers to send to the token URL of an oauth_* flow.

Show properties

object

A set of key value pairs to send as headers to the token provider.

object

Optional custom values key value pairs to be exposed to the connection. Works with all connection kinds.

object

Configuration for the live environment. This setting is ignored in watsonx Orchestrate Developer Edition because it does not include a live environment.

Show properties

enum

Whether these credentials for the connection in this environment should be shared by all users (team), or provided by each user (member).Possible values: team, member

string

The base URL of the server this application is associated with (if any). In the case of oauth connections, this may differ from the token URL which is provided via the credentials themselves.

boolean

default:false

Only set to true for oauth_auth_on_behalf_of_flow connections. When this is true, the connection will be done through an Identity Provider (IDP).

object

To configure headers and body parameters to an IDP provider when the connection type is oauth_auth_on_behalf_of_flow.

Show properties

object

A set of key value pairs to send as headers to the upstream IDP provider.

object

A set of key value pairs to send as the body to the upstream IDP provider.

object

A collection of headers to send to the token URL of an oauth_* flow.

Show properties

object

A set of key value pairs to send as headers to the token provider.

object

Optional custom values key value pairs to be exposed to the connection. Works with all connection kinds.

To import this connection, run:

BASH

orchestrate connections import -f my_app.yaml

Example connection configuration files per type

Basic Connections

A Basic connection contains two secure fields (username and password), and one insecure field (server_url).

my_app.yaml

spec_version: v1
kind: connection
app_id: my_app
environments:
    draft:  # in draft each person needs to provide their own basic credentials
        kind: basic
        type: team
        server_url: https://example.com/
    live:
        kind: basic
        type: team
        server_url: https://example.com/

Bearer Connections

An Bearer connection contains one secure field called a token, and one insecure field for the server_url.

my_app.yaml

spec_version: v1
kind: connection
app_id: my_app
environments:
    draft:  # in draft each person needs to provide their own basic credentials
        kind: bearer
        type: team
        server_url: https://example.com/
    live:
        kind: bearer
        type: team
        server_url: https://example.com/

API Key Connections

An API key connection contains one secure field called an api_key, and one insecure field for the server_url.

my_app.yaml

spec_version: v1
kind: connection
app_id: my_app
environments:
    draft:  # in draft each person needs to provide their own basic credentials
        kind: api_key
        type: team
        server_url: https://example.com/
    live:
        kind: api_key
        type: team
        server_url: https://example.com/

Key Value Connections

Key-value connections allow you to pass an arbitrary set of keys and values to upstream providers. These connections are especially useful in Python tools when you need secure configuration options that don’t fit into standard authentication categories.You can also use key-value connections to securely inject environment variables into MCP servers, enabling flexible and secure runtime configuration.

my_app.yaml

spec_version: v1
kind: connection
app_id: my_app
environments:
    draft:
        kind: key_value
        type: team
    live:
        kind: key_value
        type: team

OAuth auth code flow

OAuth Auth Code Flows provide a downstream service a field called an access_token which can be used used as an Bearer token by your tool.

**my_app.yaml**

spec_version
kind: connection
app_id: my_app
environments:
    draft:
        kind: oauth_auth_code_flow
        type: team
        server_url: https://example.com/
    live:
        kind: oauth_auth_code_flow
        type: team
        server_url: https://example.com/

🚧 OAuth auth implicit flow

OAuth Implicit Flows provide a downstream service a field called an access_token which can be used used as an Bearer token by your tool.

**my_app.yaml**

spec_version
kind: connection
app_id: my_app
environments:
    draft:
        kind: oauth_auth_implicit_flow
        type: team
        server_url: https://example.com/
    live:
        kind: oauth_auth_implicit_flow
        type: team
        server_url: https://example.com/

OAuth auth password flow

OAuth Auth Password Flows provide a downstream service a field called an access_token which can be used used as an Bearer token by your tool.

**my_app.yaml**

spec_version
kind: connection
app_id: my_app
environments:
    draft:
        kind: oauth_auth_password_flow
        type: team
        server_url: https://example.com/
    live:
        kind: oauth_auth_password_flow
        type: team
        server_url: https://example.com/

OAuth auth client credentials flow

OAuth Auth Client Flows provide a downstream service a field called an access_token which can be used used as an Bearer token by your tool.

**my_app.yaml**

spec_version
kind: connection
app_id: my_app
environments:
    draft:
        kind: oauth_auth_client_credentials_flow
        type: team
        server_url: https://example.com/
    live:
        kind: oauth_auth_client_credentials_flow
        type: team
        server_url: https://example.com/

🌐 SSO / IDP auth (on behalf of flow)

OAuth on-behalf-of flows authenticate against an identity provider that can issue tokens to downstream services on behalf of a user. This enables secure, delegated access to external systems.Currently, watsonx Orchestrate supports these flows only for agents accessed through embedded webchat.

YAML

spec_version: v1
kind: connection
app_id: workdaysso
environments:
  draft:
    kind: oauth_auth_on_behalf_of_flow
    type: member
    sso: true
    server_url: https://TBD.workday.com/ccx
    idp_config:
      header:
        content-type: application/x-www-form-urlencoded
      body:
        requested_token_use: on_behalf_of
        requested_token_type: urn:ietf:params:oauth:token-type:saml2
    app_config:
      header:
        content-type: application/x-www-form-urlencode
  live:
    kind: oauth_auth_on_behalf_of_flow
    type: member
    sso: true
    server_url: https://TBD.workday.com/ccx
    idp_config:
      header:
        content-type: application/x-www-form-urlencoded
      body:
        requested_token_use: on_behalf_of
        requested_token_type: urn:ietf:params:oauth:token-type:saml2
    app_config:
      header:
        content-type: application/x-www-form-urlencoded

You can create and manage connections directly from the CLI.

Add the Connection

Start by adding the connection using the following command. This registers the connection in watsonx Orchestrate and makes it visible in both the Connections Manager UI and the orchestrate connections list command:

orchestrate connections add -a <application_id>

At this point, the connection is registered and can be referenced by agents and tools. However, it won’t be usable until you configure it and set credentials.

Configure the Connection

Use the configure command to define the connection’s environment, credential scope, and authentication type:

orchestrate connections configure -a <application_id> --env draft -t team -k basic
orchestrate connections configure -a <application_id> --env live -t team -k basic

This step prepares the connection for use in both the draft and live environments.

Setting Credentials

Once a connection has been configured, you can set its credentials using either the CLI or the UI.

Setting credentials via the UI

Once you’ve added a connection, you can manage its credentials through the Connections Management UI, located under Manage → Connections. For member connections, each end user sets their own credentials through this interface.

Note: In the watsonx Orchestrate Developer Edition, you can only set credentials using the CLI. The UI does not support credential management in this edition. As a result, you can only fully configure OAuth connections in the SaaS or on-premises offerings, where both CLI and UI credential setup are supported.

Setting credentials via the CLI

Alternatively, you can set connection credentials via the CLI to more easily script agent setup.

Basic Connections

BASH

orchestrate connections set-credentials -a application_id \
  --env draft \
  -u username \
  -p password

Show detailed flag descriptions

enum

values: draft, live

You can choose to set credentials for either the draft environment (used in the Manage Agents preview) or the live environment, depending on where the agent will operate

string

The username of the user

string

The password of the user

Bearer Connections

BASH

orchestrate connections set-credentials -a application_id \
  --env draft \
  --token thebearertoken

Show detailed flag descriptions

enum

values: draft, live

You can choose to set credentials for either the draft environment (used in the Manage Agents preview) or the live environment, depending on where the agent will operate

string

The Bearer token to send.

API Key Connections

BASH

orchestrate connections set-credentials -a application_id \
  --env draft \
  --api-key theapikey

Show detailed flag descriptions

enum

values: draft, live

You can choose to set credentials for either the draft environment (used in the Manage Agents preview) or the live environment, depending on where the agent will operate

string

The API key to send

Key Value Connections

BASH

orchestrate connections set-credentials -a application_id \
  --env draft \
  -e 'key1=value1' \
  -e 'key2=value2'

Show detailed flag descriptions

enum

values: draft, live

You can choose to set credentials for either the draft environment (used in the Manage Agents preview) or the live environment, depending on where the agent will operate

string

A key-value pair can be used to securely pass configuration data to downstream tools or AI gateway providers. Entries are provided in the form key=value.

OAuth

OAuth supports multiple authentication flows, as outlined in the OpenAPI specification. watsonx Orchestrate can use these flows to generate authentication tokens for compatible downstream consumers. Unlike other authentication methods, such as Basic Auth or API Key, where tools receive the same credentials that were configured, OAuth connections dynamically resolve an access_token within Orchestrate. The platform generates this token on behalf of the tool and securely provides it during execution. Auth Code Flow

BASH

orchestrate connections set-credentials -a application_id \
  --env draft \
  --client-id 'clientid' \
  --client-secret 'clientsecret' \
  --authorization-url 'https://api.example.com/oauth2/authorize' \
  --token-url 'https://api.example.com/oauth2/token' \
  --scope admin

Show detailed flag descriptions

enum

values: draft, live

You can choose to set credentials for either the draft environment (used in the Manage Agents preview) or the live environment, depending on where the agent will operate

string

The OAuth connection’s client ID. This value uniquely identifies the application (watsonx Orchestrate) to the OAuth provider.

string

The OAuth connection’s client secret. This value authenticates the application (watsonx Orchestrate) with the OAuth provider.

string

default:"header"

values: header, body

Specifies how to send the OAuth credentials. Supported values: header, body.

string

The URL where watsonx Orchestrate exchanges the user authorization, client ID, and client secret to obtain an access token.

string

A comma-separated list of OAuth scopes to request. These scopes define the permissions granted to the generated token for accessing the upstream service provider.

ConnectionCredentialsEntry

Define custom field options for an OAuth request.
Use key-value pairs in the format location:<key>=<value> or <key>=<value>.
You can pass multiple values like this: -t key1=value1 -t location:key2=value2.
Valid locations are: header, body, and query. If you omit the location, it defaults to header.

ConnectionCredentialsEntry

Define custom field options for an oauth_auth_code_flow auth server request.
Use key-value pairs in the format location:<key>=<value> or <key>=<value>.
You can pass multiple values like this: --auth-entries key1=value1 --auth-entries location:key2=value2.
The only valid location is query, which also serves as the default if you omit it.

🚧 Implicit flow
Currently, watsonx Orchestrate does not support OAuth implicit flows. Support for this feature is coming soon. Password flow

BASH

orchestrate connections set-credentials -a application_id \
  --env draft \
  --client-id 'clientid' \
  --client-secret 'clientsecret' \
  --username 'username' \
  --password 'password' \
  --token-url 'https://api.example.com/oauth2/token' \
  --scope admin

Show detailed flag descriptions

enum

values: draft, live

You can choose to set credentials for either the draft environment (used in the Manage Agents preview) or the live environment, depending on where the agent will operate

string

The clientId of the OAuth connection. This is used to uniquely identify the application (watsonx Orchestrate) to the oauth provider.

string

The clientSecret of the Oauth connection. This is used to authentication the application (watsonx Orchestate) to the oauth provider.

string

This is the url watsonx Orchestrate will exchange the user authorization, client id and secret to to fetch an access token.

string

A comma separated list of oauth scopes to request for the user to grant the generated token certain privileged accesses to the upstream service provider.

Client Credentials flow

BASH

orchestrate connections set-credentials -a application_id \
  --env draft \
  --client-id 'clientid' \
  --client-secret 'clientsecret' \
  --token-url 'https://api.example.com/oauth2/token' \
  --scope admin

Show detailed parameter descriptions

enum

values: draft, live

You can choose to set credentials for either the draft environment (used in the Manage Agents preview) or the live environment, depending on where the agent will operate

string

The clientId of the OAuth connection. This is used to uniquely identify the application (watsonx Orchestrate) to the oauth provider.

string

The clientSecret of the Oauth connection. This is used to authentication the application (watsonx Orchestate) to the oauth provider.

string

default:"header"

values: header, body

A comma separated list of oauth scopes to request for the user to grant the generated token certain privileged accesses to the upstream service provider.

string

This is the url watsonx Orchestrate will exchange the user authorization, client id and secret to to fetch an access token.

string

A comma separated list of oauth scopes to request for the user to grant the generated token certain privileged accesses to the upstream service provider.

🌐 SSO / IDP auth (on behalf of flow)

BASH

orchestrate connections set-identity-provider --app-id workday \
  --env draft \
  --url https://idp-server/oauth2/v2.0/token \
  --client-id clientid \
  --client-secret clientsecret \
  --scope scope \
  --grant-type urn:ietf:params:oauth:grant-type:jwt-bearer

Show detailed flag descriptions

enum

values: draft, live

You can choose to set credentials for either the draft environment (used in the Manage Agents preview) or the live environment, depending on where the agent will operate

string

You can choose to set credentials for either the draft environment (used in the Manage Agents preview) or the live environment, depending on where the agent will operate

string

The OAuth connection’s client ID. This value uniquely identifies the application (watsonx Orchestrate) to the OAuth provider.

string

The clientSecret of the Oauth connection. This is used to authentication the application (watsonx Orchestate) to the oauth provider.

string

The URL where watsonx Orchestrate exchanges the user authorization, client ID, and client secret to obtain an access token.

string

A comma separated list of oauth scopes to request for the user to grant the generated token certain privileged accesses to the upstream service provider.

ConnectionCredentialsEntry

BASH

orchestrate connections set-credentials --app-id workday \
  --env draft \
  --client-id clientid \
  --token-url https://token-server/ccx/oauth2/ibmsrv_dpt1/token \
  --grant-type urn:ietf:params:oauth:grant-type:saml2-bearer

Show detailed flag descriptions

enum

values: draft, live

You can choose to set credentials for either the draft environment (used in the Manage Agents preview) or the live environment, depending on where the agent will operate

string

The OAuth connection’s client ID. This value uniquely identifies the application (watsonx Orchestrate) to the OAuth provider.

string

The URL where watsonx Orchestrate exchanges the user authorization, client ID, and client secret to obtain an access token.

string

The grant type of the identity provider’s auth service.

ConnectionCredentialsEntry

Release Notes

Get Started

Build

Analyze

watsonx Orchestrate Developer Edition

watsonx Orchestrate ADK MCP Server

Reference

Legal notices

Creating connections

Adding and configuring connections

Example connection configuration files per type

Setting Credentials

Setting credentials via the UI

Setting credentials via the CLI

Basic Connections

Bearer Connections

API Key Connections

Key Value Connections

OAuth

🌐 SSO / IDP auth (on behalf of flow)

​Adding and configuring connections

​Example connection configuration files per type

​Setting Credentials

​Setting credentials via the UI

​Setting credentials via the CLI

​Basic Connections

​Bearer Connections

​API Key Connections

​Key Value Connections

​OAuth

​🌐 SSO / IDP auth (on behalf of flow)

Adding and configuring connections

Example connection configuration files per type

Setting Credentials

Setting credentials via the UI

Setting credentials via the CLI

Basic Connections

Bearer Connections

API Key Connections

Key Value Connections

OAuth

🌐 SSO / IDP auth (on behalf of flow)