If your organization only allows AI traffic through a corporate API gateway, you can still use SmartSuite AI. A common example is Azure API Management (APIM) sitting in front of Azure OpenAI. You set up an Azure connection in AI Control Center that sends your gateway's required headers with every request. This article is for Workspace Administrators who configure AI connections.
Plan Availability | All plan types. |
Permissions | Workspace Administrators only. |
Related Reading |
Overview
Many enterprise security teams require all LLM calls to pass through a governed gateway rather than going straight to the provider. These gateways usually do three things:
They authenticate with their own header, such as Ocp-Apim-Subscription-Key, instead of a provider API key.
They require extra headers for cost allocation or approval routing.
They use a non-standard path in front of the usual Azure OpenAI route.
The Azure connection type in Providers and Models supports all three. Once saved, a gateway connection behaves like any other connection:
It appears in the connections list and in the Select Connection dropdown for the AI Workflow Agent and AI Field Agent.
Its usage shows up in Used In and Activity History.
Solution builders just pick the connection. They never see or handle the headers.
How to Set It Up
Go to Workspace Administration → AI Control Center and open Providers and Models.
Add a new connection and select the Azure AI provider.
Check Enable Custom Connection. The gateway settings appear.
Enter your gateway’s Endpoint and API version. If your gateway adds a path before the standard Azure OpenAI route, enter it in Base path (for example,
/genai/azure).Choose an API route (see below).
Select your model. If your gateway can’t return a list of deployed models, a Deployment name field appears instead. Type the exact deployment name configured on your gateway.
Fill in or leave blank the API key:
Leave it blank if your gateway authenticates with a header instead.
Fill it in if your gateway also expects a standard Azure API key.
Under Custom Headers, click Add header for each header your gateway requires.
Enter the Header name and Header value.
Turn on Secret for any value that’s a credential.
Complete the remaining fields as you would for any connection: name, description and Internet access.
Test the connection. SmartSuite sends a test prompt through your gateway using your endpoint, headers and API route.
Choose which solutions and features can use the connection, then click Add Connection.
Note: The endpoint must be an https:// address that’s reachable over the public internet. SmartSuite can’t connect to gateways on private or internal network addresses.
Custom Headers
Each header row has a name, a value, a Secret toggle and a remove control.
Header names can contain only letters, numbers and hyphens. Each name must be unique within the connection and can be up to 128 characters.
Header values can be up to 1,024 characters. Rows left empty are ignored when you save.
Secret turns on automatically for headers named Ocp-Apim-Subscription-Key, Authorization, api-key or x-api-key. You can change it for any header.
Secret values are encrypted at rest and masked, just like API keys.
When you edit the connection later, you’ll see only a partial preview of each secret value.
The stored value stays in place unless you type a new one.
Non-secret values, such as a charge code or approval group, show in plain text and can be edited directly.
Note: Custom headers are available on the Azure connection type only.
API Route
Chat Completions: Use this for most corporate gateways.
Responses API: Use this only if your gateway explicitly routes
/v1/responses.
Testing and Changes
When a test is required:
When you create the connection.
When you change the endpoint, base path, headers or API route.
When you turn Enable Custom Connection on or off.
What counts as a pass: Any successful response from the gateway. If the test fails, the gateway’s response is shown so you can correct your values and try again.
Tip: Sometimes the gateway starts rejecting requests after setup, for example because a subscription key expired. When that happens, the connection is treated as invalid and Workspace Administrators receive the invalid-connection email alert. Update the header value and test again.
Practical Scenarios and Use Cases
1. Gateway authenticates with a subscription key
Scenario: Your Azure OpenAI deployment sits behind Azure API Management, and requests need Ocp-Apim-Subscription-Key rather than an Azure API key.
Solution: Leave API key blank, add Ocp-Apim-Subscription-Key as a custom header, and keep Secret on.
2. Cost allocation and approval routing
Scenario: Your finance or governance team requires every AI request to carry a charge code and an approval group.
Solution: Add each one as a custom header with Secret off. Every request made through the connection carries them, whichever solution or feature triggers it.
3. Gateway only supports Chat Completions
Scenario: Your gateway routes chat/completions but doesn’t route /v1/responses yet.
Solution: Set API route to Chat Completions and test the connection.
4. Gateway can’t list its models
Scenario: Model selection doesn’t populate because your gateway can’t return a list of deployed models.
Solution: Type the exact deployment name into Deployment name, then test the connection.