Connections are composed of 3 parts:
  1. Application ID (app_id): A unique identifier that distinguishes the connection within your environment.
  2. 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)
  1. 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.
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/
To import this connection, run:
BASH
orchestrate connections import -f my_app.yaml

​
Example connection configuration files per type

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/
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/
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 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 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 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 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 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/
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

​
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.
Connections UI

Connections UI

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

​
Bearer Connections

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

​
API Key Connections

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

​
Key Value Connections

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

​
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
🚧 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
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

​
🌐 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
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