Trusted connections

A trusted connection stores the connection details for an external AI provider, including the endpoint and the credentials used to authenticate. AI models reference a trusted connection instead of storing their own connection details. This lets you create and use an AI model without access to the underlying provider credentials.

Requirements

To create, view, edit, or delete trusted connections, you need:

• A valid AI workflows license.

• The sysadmin role.

• All credentials must be stored using a secrets manager. Keys or secrets cannot be entered as plaintext and must be provided by secret reference.

• The requirements for the specific Connection type you are configuring:

  • OpenAI and OpenAI-compatible connections

  • Amazon Bedrock connections

  • Google Gemini Enterprise Agent Platform connections

Configuration

To view Trusted connections, navigate to AI > Trusted connections. The table lists each connection’s Name, Description, and Type. To configure a new connection, follow these steps:

1. From the Trusted connections pane, click Configure trusted connection.

2. In the Configure trusted connection dialog, enter a Connection name. Users select this name when they connect a model. For example: claude4_5_connection.

3. Optionally, enter a Description for the connection.

4. From the Connection type menu, select OpenAI / OpenAI compatible, Amazon Bedrock, or Google Gemini Enterprise Agent Platform.

5. Configure the connection information for the selected type, as described in the following sections:

   • OpenAI and OpenAI-compatible connections

   • Amazon Bedrock connections

   • Google Gemini Enterprise Agent Platform connections

6. Click Test connection to verify the connection.

7. Click Save.

OpenAI and OpenAI-compatible connections

Select OpenAI / OpenAI compatible to connect to OpenAI or a compatible API provider. Choose an Authentication method and provide the required connection details described in the following sections.

You can connect to OpenAI-compatible providers such as Azure OpenAI or Gemini by selecting this connection type. See Compatible APIs.

Authenticate with an API key

Your API key must have permission to call the listModels endpoint. This is used to verify the connection when you click Test connection.

• OpenAI endpoint: Specify the URL for the OpenAI API endpoint. For example, https://api.openai.com/v1.

• OpenAI API key: Specify the secret reference for the OpenAI API key. This value is optional when using a compatible OpenAI API that does not require a key.

Authenticate with OAuth 2.0

To enable authentication with OAuth 2.0, you must add the ai.agent.trusted-connections.oauth.enabled=true configuration property in config.properties.

OAuth 2.0 authentication only uses the client credentials grant type. The password and authorization code grant types are not supported. Your OAuth token must have permission to call the listModels endpoint. This is used to verify the connection when you click Test connection.

Set the following caching properties in config.properties:

ai.client.cache.refresh.enabled=true
ai.client.cache.refresh.interval=1s
ai.client.oauth.refresh-skew=60s

Caution

The value of ai.client.oauth.refresh-skew must be greater than ai.client.cache.refresh.interval.

The following table describes OAuth caching configuration properties:

OAuth token caching configuration properties

Property name	Description	Default
ai.client.cache.refresh.interval	Specifies the interval AI model connections are refreshed. Must be set lower than ai.client.oauth.refresh-skew to ensure OAuth tokens are refreshed before expiration. Valid values are 1s to 10s.	1s
ai.client.oauth.refresh-skew	Specifies when to refresh an OAuth 2.0 access token before it expires. Must be greater than ai.client.cache.refresh.interval. Valid values are 5s to 10m.	60s
ai.client.oauth.token-cache-duration	Specifies the duration to keep OAuth 2.0 access tokens cached in memory. If a token expires while cached, it is evicted and a new token is retrieved on the next request. Valid values are 5s to 10h.	30m
ai.client.oauth.max-cached-tokens	Sets the maximum number of OAuth 2.0 access tokens to cache in memory. When the limit is reached, older entries are evicted to make room for new tokens. The minimum value is 1.	1000

Once you have added the necessary configuration properties, enter the following connection information in the Configure trusted connection dialog:

• OpenAI endpoint: Specify the URL for the OpenAI API endpoint. For example, https://api.openai.com/v1. The endpoint is required when using OAuth 2.0.

• Token URL: Specify the HTTPS URL of the OAuth 2.0 token endpoint. For example, https://example.com/oauth2/token.

• Client ID: Specify the client ID issued by your identity provider.

• Client secret: Specify the secret reference for the client secret issued by your identity provider.

In Additional configuration, you can optionally specify the following:

• Scope: Specify the OAuth 2.0 scope to request when obtaining an access token. For example, openid profile email. Separate multiple scopes with spaces.

• Audience: Specify the audience parameter to send to the token endpoint. Some identity providers require this value.

Note

OAuth 2.0 and API key authentication are mutually exclusive. When you select OAuth 2.0, you cannot add an Authorization header in Additional headers. SEP manages the Authorization header using the OAuth bearer token.

Amazon Bedrock connections

In the Connection information section, select one of the following Authentication methods. SEP performs a list foundation models check. The credentials used must have the bedrock:ListFoundationModels permission. This is used to verify the connection when you click Test connection.

Authenticate using AWS default credentials

When authenticating with AWS default credentials, use your AWS credentials that are already configured for your environment. Starburst uses the AWS Default credentials provider chain to detect credentials.

Authenticate with an AWS IAM role

When authenticating with an AWS IAM role, enter the following details in the Configure trusted connection dialog:

• AWS IAM role ARN: Specify the ARN of the IAM role to assume when connecting to AWS.

• STS AWS access key ID: Specify the secret reference for the Security Token Service (STS) AWS access key to use for authentication for the specified role.

• STS AWS secret access key: Specify the secret reference for the Security Token Service (STS) AWS secret key to use for authentication for the specified role.

• AWS region code: The AWS region code. For example, the region code for US East (Ohio) is us-east-2.

  For more information about AWS regions and region codes, read the AWS documentation.

Authenticate with an AWS access key

When authenticating with an AWS access key, enter the following details in the Configure trusted connection dialog:

• AWS access key ID: Specify the secret reference for the AWS access key to use for authentication.

• AWS secret access key: Specify the secret reference for the AWS secret key to use for authentication.

• AWS region code: The AWS region code. For example, the region code for US East (Ohio) is us-east-2.

Authenticate with AWS anonymous credentials

When authenticating with AWS anonymous credentials, enter the following details in the Configure trusted connection dialog:

• AWS region code: Specify the AWS region code for the proxy or gateway that manages authentication and routes requests to Amazon Bedrock. For example, the region code for US East (Ohio) is us-east-2. Ensure the region code matches the Amazon Bedrock endpoint your proxy uses. For more information about AWS anonymous credentials, read the AWS documentation.

Regardless of the selected AWS Authentication method, in Additional connection configuration, you can specify an Alternative Bedrock endpoint to route requests through a proxy, custom endpoint, or an alternate Amazon Bedrock endpoint.

Google Gemini Enterprise Agent Platform connections

Select Google Gemini Enterprise Agent Platform to connect to the Gemini Enterprise Agent Platform for access to Google Gemini language models and partner models.

Before you configure this connection, create a Google Cloud service account grant it the Vertex AI User (roles/aiplatform.user) role, and generate a service account key in JSON format. For the full list of roles, read the Vertex AI access control documentation.

In the Connection information section, enter the following details:

• Service account key: Specify the secret reference for the Google Cloud service account JSON key. For example, ${asm:test:vertex_key}.

• Location: Specify the Google Cloud region for Vertex AI. For example, us-central1.

Starburst reads the Google Cloud project ID from the service account key. When you click Test connection, Starburst verifies the credentials against the Vertex AI API.

Note

Google Gemini Enterprise Agent Platform connections support language models only. Embedding models are not supported.

Additional headers

In the Additional headers section, you can optionally add custom HTTP headers to include with every request that uses this connection.

• Click Add header.

• Header name: Specify the header name or key. For example, an Authorization header sends a bearer token that allows your proxy to authenticate the request before it reaches the Amazon Bedrock service.

• Values: Specify one or more comma-separated values for the header. For example, the Authorization header uses the bearer token value to authorize the request.

Note

These headers apply to every model that uses this connection. To add headers for a single model, use Custom request headers in the model configuration dialog. See Model configuration.

Edit or delete a trusted connection

1. Navigate to AI > Trusted connections.

2. In the row for the connection, click the more_vert options menu.

3. Click Edit to change the connection’s information, or Delete to remove it.

Caution

Editing or deleting a trusted connection affects every AI model that references it.