Authentication types overview

Edit online

Authentication defines how watsonx Orchestrate establishes trust with a third‑party application when a tool sends a request. Every connection uses an authentication method to prove its identity to the external system and obtain authorization for the requested action. The authentication type that you select determines how credentials are used, which parameter fields are required, and whether access uses a shared identity or an individual user identity.

Authentication types determine which configuration parameters the connection requires such as URLs, scopes, or client credentials and which credential model applies (team or member). When a tool includes an OpenAPI specification, watsonx Orchestrate analyzes the security schema, scopes the UI to the relevant fields, and pre‑populates available authentication parameters to reduce configuration errors. Sensitive values, such as client secrets, are never auto‑filled.

When you configure authentication, choose the authentication type that the target application supports. Authentication types are not interchangeable. Using an unsupported type results in authentication failures, rejected tokens, or incorrect user context. Requests return errors such as 401 Unauthorized, 403 Forbidden, or token validation failures, and the connection cannot function.

The authentication type that you choose defines:

  • How identity is established: for example, through a static key, username or password, pre‑issued token, custom headers, or OAuth flows.

  • Which credentials are required: team or member

  • Which configuration parameters must be supplied such as authorization URLs, token URLs, scopes, client credentials, server URLs, or custom key‑value definitions.

Supported authentication types

watsonx Orchestrate supports the following authentication types:

The following tables summarize each authentication type and its configuration requirements.

API key

API key authentication uses a unique identifier (API key) for client authentication, and the API key is sent in a specified location (header, parameter, or cookie) within the request to authenticate.

  • You can use this method when the external system supports static key authentication and the key is long‑lived and stable. You can also use this method when the provider accepts API keys in a header, query parameter, or cookie.

  • Credential model: team or member, depending on what the application allows.

  • Required configuration parameters: server URL, API key location, security scheme.

Basic Auth

Basic authentication uses a username and password combination to authenticate.

  • You can use this method when the target application accepts HTTP Basic (username/password) on every request and when a static credential must be sent in the Basic Authorization header.

  • Credential model : team or member, depending on the external application’s requirements.

  • Required configuration parameters: server URL.

Bearer Token

Bearer token authentication sends a pre‑issued access token in the Authorization: Bearer <token> header for each request, and tokens often originate from an OAuth server or trusted provider pipeline.

  • You can use this method when you already have a token string to send as Authorization: Bearer <token>, when the connection does not run OAuth flows, and when the token is static but time‑bound and must always be sent in the Authorization header

  • Credential model: team or member, depending on who the token belongs to.

  • Required configuration parameters: server URL.

Key Value Pair

Key‑Value Pair authentication sends a set of key‑value pairs in the request, where each key‑value pair consists of a key and a corresponding value.

  • You can use this method when the application requires custom headers or parameters that do not fit standard authentication patterns (for example, X‑Tenant‑Id, X‑Org, X‑Client), when flexible “bring‑your‑own‑fields” options are needed, and when the provider uses custom header names that mimic API‑key patterns.

  • Credential model: team only because this method relies on static values that are controlled by the integration owner.

  • Required configuration parameters: server URL, Key-Value

OAuth2 Authorization Code

OAuth2 Authorization Code authentication is designed for applications that need to access resources on behalf of a user.

  • You can use this method when the target application supports OAuth with user sign‑in and consent to obtain tokens. You can also use this method when user‑delegated access that requires an individual identity is needed and when the application supports refresh tokens for long‑lived sessions.

  • Credential model: team or member.

Team: builder authorizes a shared integration identity Member: the user authorizes with their own identity.

  • Required configuration parameters: server URL, token URL, authorization URL, client ID, client Secret, scope, token request field, auth request field.

OAuth2 Client Credential

OAuth2 Client Credentials authentication is designed for server‑to‑server authentication.

  • You can use this method for service‑to‑service access where no user identity is required. You can also use this method when the integration must authenticate as the application or service and when no browser or consent step is involved. It is also suitable when no long‑lived refresh token is required and the client remints a new token by using its credentials.

  • Credential model: team only (service identity). Member identity does not apply to this flow.

  • Required configuration parameters: Server URL, token URL, client ID, client Secret, grant Type, send Credentials Via, scope, token request field.

OAuth2 Password

OAuth2 Password authentication is suitable for trusted applications that directly handle user credentials, where the application sends the user’s username and password to the token URL to obtain an access token; the grant type is password.

  • You can use this method only when the identity provider still supports the OAuth2 Password (ROPC) flow. You can also use this method when the connection must collect the user’s username and password directly to obtain an access token. This method is suitable when no redirect or consent screen is involved because the credentials exchange occurs directly for a token.

  • Credential model: team or member, depending on which identity the external system associates with the submitted credentials.

  • Required configuration parameters: Server URL, token URL, client ID, client Secret, grant Type, scope, token request field.

Authentication configuration fields

The parameter fields describe the configuration values required by each authentication method. These fields identify the endpoints, credentials, and parameters that watsonx Orchestrate uses to authenticate with the target application. The following table explains what each field represents and how it is used during authentication.

Field

Details

Server URL

The base URL of the server that hosts the protected resources. All authentication and resource requests are sent to this URL.

API Key Location

The API key can be sent in different locations within the request, such as the header, query, or cookie. Choose the API key location (header, query, or cookie).

Security scheme

For OpenAPI tools requiring an API Key connection type, configure the security scheme in your OpenAPI specification. For more details, refer to Additional features of OpenAPI tools.

Key-Value

Each key-value pair consists of a key and a corresponding value. The key identifies the type of information being sent, while the value contains the actual data. For example, a key might be "client_id" and its corresponding value might be the unique identifier for the client application. You can add more key‑value pairs when the application requires them.

Token URL

Specify the token URL value relative to the server URL. The Token URL is typically provided by the authorization server during the registration of the application.

Authorization URL

This is the endpoint on the authorization server where the client redirects the user for authentication and authorization. The user grants or denies the client's request for access to their resources.

Client ID

A unique identifier for the client application. Get the client ID from your account user interface.

Client Secret

A secret key that is known only to the client and the authorization server.

Scope

Scope is a way to limit the access. It defines the specific permissions or resources to which access is allowed.

Token request field

It is used to include additional parameters that the authorization server needs when the server exchanges a code or credentials for an access token. They are required for custom implementations where the server expects extra details, such as a verification code or resource ID.

Auth request field

It is used to provide extra information during the login step at the OAuth authorization endpoint. They help the server identify the correct tenant or identity provider and are essential for setups that require custom parameters like idp or tenant_id.

Grant Type

The grant type is always "client_credentials". This value indicates to the authorization server that the client is requesting an access token by using the Client Credential flow.

Send Credentials Via

Specify how the credentials are sent (header or body).

Tip:

The Token request field is intended only for additional or custom parameters that do not contain sensitive information. For security‑sensitive values such as passwords, API keys, or client secrets, use the credential fields.

Callback URL

When you use the OAuth2 Authorization Code, you must configure a callback URL in the external application where the client ID and client secret were generated. The callback URL tells the authorization server where to send the authorization code after the user signs in and consents.

The callback URL format is:

`<env_url>/mfe_connectors/api/v1/agentic/oauth/_callback`

For example, if your watsonx Orchestrate environment URL is:

`https://dl.watson-orchestrate.ibm.com/`

Then, the callback URL is:

`https://dl.watson-orchestrate.ibm.com/mfe_connectors/api/v1/agentic/oauth/_callback`

The external application must be configured to allow redirects to this callback URL for OAuth 2.0 Authorization Code flows to succeed.

Create callback URL

To create the callback URL from the service instance URL:

  1. To create the callback URL, first you need to find the service instance URL. Do one of the following to obtain the service instance URL:

    • From watsonx Orchestrate

      1. Click the Profile icon.

      2. Select Settings.

      3. Click API details.

      4. Copy the Service instance URL.

The following image shows where to locate the service instance URL in the profile settings.

Service instance URL in watsonx Orchestrate settings

  • From AI assistant builder

    1. Click Assistant builder.

    2. Click Assistant settings.

    3. In the Assistant IDs and API details section, click View details.

    4. Copy the Service instance URL.

The following image shows where to find the service instance URL in the AI Assistant Builder.

Service instance URL in AI Assistant Builder

  • From environments

    1. Click Assistant builder.

    2. Click Environments.

    3. Click Settings next to the draft environment.

    4. On the API details window, copy the Session URL.

The following image shows where to find the service instance URL in environment settings.

Service instance URL in environment settings

Example for service instance URL

   `https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/12345678-abcd-90ef-1234-abcdef123456`

  1. Collect the base URL of the string, excluding api from the start.

After you remove the API from the start of the service instance URL, the base URL is:

   `https://us-south.watson-orchestrate.cloud.ibm.com`

  1. Combine base URL with end string.

End string:

   `mfe_connectors/api/v1/agentic/oauth/_callback`

After you combine the base URL with end string, you get the following URL:

   `https://us-south.watson-orchestrate.cloud.ibm.com/mfe_connectors/api/v1/agentic/oauth/_callback`
Tip:

The callback URL for OAuth2 Authorization Code is generated from your tenant’s base URL and an end string. Because the base URL is specific to each tenant, the callback URL that is generated is unique to your environment. The callback URL does not apply to OAuth2 Client Credentials, OAuth2 Password, or OAuth2 On Behalf Of flow (SSO).

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 values are available in the OpenAPI specification. Enter sensitive credentials manually because they are never auto-filled for security reasons.

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

Important:

  • Connection name and Connection Id are auto-suggested, but you can modify these values before you continue.

  • watsonx Orchestrate does not auto-fill custom auth types. This limitation 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 earlier) are auto-populated.

  • Enter client_id and client_secret manually because they are never auto-populated.