Skip to content
CortexDocs

Connect or repair a provider

Configure a provider credential, inspect a fresh connection check, and verify a supported client request.

A provider connection holds the company key Gateway uses for upstream requests. An Egress organization needs at least one enabled provider with a stored company key before clients can connect; until then, admins see Add your company's provider key first on Connect. Members then follow the first-request guide.

Gateway has six destinations in the sidebar: Overview, Usage, API Keys, Routing, Access & limits and Security. Providers are under Routing, next to the Overview, Configuration and Sessions tabs.

Before you begin

Required

  • Admin access

    Use Admin access in the intended organization.

  • Atlas for Defender devices

    Cortex Atlas is required only to configure providers for enrolled Defender devices. Egress organizations and their clients need neither Atlas nor Defender.

  • Provider credentials

    Have the provider's approved endpoint and company API key ready. Members use a separate personal capture token from their client.

Watch the setup

This 1:29 recording connects OpenAI as the example provider. Use the provider and endpoint your organization approved.

Guided tutorial1:29

Connect a providerUse the chapter list to move through the walkthrough.

Choose a provider

  1. Open Routing → Providers for the intended organization.
  2. Select Add connection.
  3. Select Configure on the provider for the upstream account. A provider that is already connected shows Edit instead.

Match the model family to the service handling the request. Gemini is a model family; Google, Google Cloud and other serving platforms can use different endpoints, credentials and models. Use the service and connection choices supported by your deployment. Choose a model lists catalog IDs and rates; catalog membership does not establish account access.

The selector offers Anthropic, OpenAI, Google Gemini, Grok (xAI), Fireworks and Perplexity. Cortex Router is a separate routing endpoint option.

Choose a provider preset from the Add connection dialogOpen in Cortex

Configure a provider

  1. Confirm Endpoint matches the approved endpoint for that account.
  2. Enter your company's provider key in API key. An enabled connection requires a stored company key.
  3. Review Enabled.
  4. Expand Advanced only if the deployment requires added headers or stripped request fields.
  5. Select Save connection. A successful save refreshes the provider list.
  6. Find the saved row and expand its provider name. Confirm the endpoint, stored credential and enabled state.
Set the endpoint, company key and enabled state in Configure connectionOpen in Cortex
  • To change a saved connection, select its row, then select Edit.
  • Leave API key blank to keep the stored value, or enter a replacement before saving.
  • Stored credentials are hidden after saving.
  • Disable keeps the saved settings and stops the connection from being used.
  • Remove asks you to confirm with Remove connection, then deletes the configuration and its stored API key.
  • Cancel with unsaved input asks Discard provider changes? Select Discard changes to leave without saving.

Connection fields

FieldWhat to confirm
ProviderThe upstream account being connected
EndpointThe endpoint approved for that account and deployment
API keyThe organization-managed provider key, separate from a member's personal Cortex API key
EnabledWhether the connection is configured for use
AdvancedOnly the header or field-handling changes required by the deployment
Connection testThe saved credential and configuration version checked, with the date and time of the check

Verify provider access

Review provider connections on the Providers page, with each endpoint, credential state and statusOpen in Cortex
  1. In the refreshed provider list, confirm the intended organization, provider, enabled state and API key configured status.
  2. Select the provider row to open its panel. Check Endpoint, Credentials, Connection and Request handling.
  3. In the selected provider panel, select Check API key. The check requires Admin access, an enabled provider and a stored company key.
  4. Read the result under Connection test and the date and time beside it. Verified confirms the provider metadata credential check for that saved configuration, and the pill at the top of the panel changes from Saved to Verified. If settings changed, refresh the row before checking again.
Saved OpenAI connection with the connection test not checked yetOpen in Cortex

A connection check tests the saved credential against provider metadata. Verify model access and generation with a new request on the path your members use.

Verify with an Egress client

This check needs no Defender installation or Atlas subscription.

  1. Follow Send your first request with a personal cct_ capture token and a model the provider account can access.
  2. Confirm the provider response. It confirms forwarding for that request.
  3. If Atlas is enabled, find the matching activity in User profiles. If policy refuses the request, use Troubleshoot refusals.

Verify on enrolled Defender devices

  1. Allow the enrolled device to refresh its configuration. Cortex Router configuration changes require a device restart.
  2. From a supported AI tool on that device, send a new request through its configured provider path. Use a model the provider account can access.
  3. Confirm the provider response. Find the matching captured activity separately in Atlas. If policy refuses the request, use Troubleshoot refusals.

A provider response confirms forwarding on that path. Saving configuration alone does not establish delivery. Provider account access, region, data-retention terms and negotiated prices are separate from catalog availability.

Replace an invalid credential

OpenAI connection panel showing Invalid credentials after a connection testOpen in Cortex
  1. Find the connection marked Needs attention, and confirm Connection test shows Invalid credentials.
  2. Select that connection's row, then select Edit.
  3. Enter the replacement API key. Leaving this field blank keeps the stored key.
  4. Select Save connection and confirm the refreshed row's endpoint, API key configured status and enabled state.
  5. Select the refreshed row to open its panel, then select Check API key again. Confirm Connection test shows a new result and date, and the pill at the top of the panel reads Verified.
  6. Send a new request with an accessible model and confirm the response: from an Egress client, or from an enrolled device after its configuration refreshes.

Troubleshooting

ResultNext action
This provider is already configuredEach provider has one connection. Select its row, then select Edit.
Save is disabledConfirm the Admin role, endpoint and required company key. Read any field validation message.
Save failsRead the returned error. If the configuration changed since you opened it, reload the saved row and review your edit again.
Provider row is missingClear the Provider and Status filters, then confirm the organization.
Check API key is disabledConfirm Admin access, an enabled provider and a stored key. Use a saved provider connection for the check.
Invalid credentialsReplace the company key on the saved provider, then check again.
Access deniedReview the upstream account's permission and approved endpoint.
Check unsupported or no check control is shownThis path does not establish a check result. Ask the administrator to confirm supported checking for this deployment.
The connection check fails or times outRead the returned provider error, resolve it and retry the check.
Provider settings changedRefresh the saved row before checking again.
Connection is disabledReview Enabled in Edit connection before testing.
Authentication fails after replacementConfirm the intended company key, provider account and endpoint, then confirm configuration refresh on the device.
Shared Egress returns provider_not_configuredAsk the administrator to confirm the enabled provider connection and model access.