Skip to content
CortexDocs

Connect a client to Gateway

Get your personal credential, connect an existing SDK or AI tool, and verify your first Gateway request.

Gateway Overview and spend over timeOpen in Cortex
  • Gateway calls the enabled provider with organization-managed credentials.
  • Shared Gateway forwarding does not require a local Cortex Defender installation or a Cortex Atlas subscription.

For an existing OpenRouter setup, follow Migrate from OpenRouter.

Before you begin

Required

  • Cortex account

    Use your account in the intended organization. If your company is not on Cortex yet, create your organization first; you become its first admin.

  • Client Gateway URL

    Cortex shows the Gateway URL in each client's setup. Anthropic clients and Claude Code use https://agent.chaoslabs.co/gateway. OpenAI SDKs, Codex and Cursor use https://agent.chaoslabs.co/gateway/v1. cURL posts to https://agent.chaoslabs.co/gateway/v1/chat/completions.

  • Enabled model ID

    Use an exact model ID that Gateway routes for your organization; the model catalog lists model IDs. Members can ask their administrator for the model ID.

Set up Gateway for a new organization

The first admin of a new organization connects a provider before anyone sends a request. If your organization already uses Gateway, continue to Sign in and create an API key.

Set up with your agent
Copy this page into Claude Code, Codex or another coding agent and it walks you through the steps.
You still: sign in, add your company's provider key and store your API key.
  1. Sign in to Cortex. In the header, open View and select Gateway, or select Gateway in the left menu if your workspace shows it there.
  2. Open Routing → Providers and select Add connection. Select Configure on the provider, enter the company's key for that provider in API key, make sure Enabled is on and select Save connection. See Providers for the connection fields.
  3. Open API Keys and select Connect a client. Choose Claude Code, Codex, Cursor, Anthropic SDK, OpenAI SDK or curl.
  4. Under 1. Add your API key, paste an existing key into the Paste API key field, or select Create a new key and save the key it shows.
  5. Copy the client setup shown below the key. It already contains the Gateway URL.
  6. Start the client, or send the curl test request, then confirm the request in Cortex.

If Connect shows Add your company's provider key first, no enabled provider connection has a key. Select Add a provider key to open the provider configuration.

Sign in and create an API key

Your personal cct_ capture token identifies the person or service account sending a request. Cortex calls it an API key. Use it as CORTEX_API_KEY. Gateway uses a separate organization-managed provider key for the upstream call; administrators manage that key in provider configuration.

  1. Sign in to Cortex with your organization account and open your profile.
  2. Select Settings.
  3. Under Devices & API keys, select Create API key.
  4. Optional: enter a name in Label (optional), then select Create API key again.
  5. On API key created, copy the key and store it in your approved secret manager. Cortex shows it once.
  6. Select I've saved this secret somewhere safe., then select Done.

The Connect to the Gateway section further down the same page shows your Gateway URL and a ready-made snippet for each client. If it is not shown, use the Gateway URL listed under Before you begin.

This 1:28 recording creates a key and sends a request through Gateway.

Guided tutorial1:28

Create an API key and send a requestUse the chapter list to move through the walkthrough.

Load the token through your client's supported secret-loading mechanism. Keep tokens out of source control, shared configuration, screenshots and client logs. If a token is exposed, generate a replacement and revoke the exposed token.

If you do not see Create API key or key creation fails, ask your administrator to enable API key creation or provide a client token. Shared Egress requires this key even when Defender is not installed.

The token identifies its owner. It is not a project-scoped key or a separate per-key budget. Organization, Team and Member controls apply to the identified account.

Service accounts

For an automated client, ask an administrator to issue a cct_ capture token on behalf of its service account. The token remains bound to that account; it does not become a project-scoped key.

Send your first request

Select your client below and send a short test request. Use the Gateway URL shown in Cortex as given; do not append a Gateway path that is already present.

  • Set CORTEX_BASE_URL to the Gateway URL that Cortex shows for the selected client.
  • Load your personal cct_ capture token into CORTEX_API_KEY from your approved secret manager.
  • Replace <organization-enabled-model> with a model ID that Gateway routes for your organization.

CORTEX_BASE_URL for cURL is the complete request URL shown in Cortex, not an SDK base.

bash
curl "$CORTEX_BASE_URL" \
  --request POST \
  --header "Authorization: Bearer $CORTEX_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "<organization-enabled-model>",
    "messages": [{"role": "user", "content": "Summarize these release notes in one sentence."}]
  }'

Response shape

{
  "id": "chatcmpl_01",
  "object": "chat.completion",
  "model": "<response-reported-model>",
  "choices": [{"message": {"role": "assistant", "content": "A concise release-note summary."}}],
  "usage": {"prompt_tokens": 23, "completion_tokens": 8, "total_tokens": 31}
}

Verify the provider response

A successful provider response confirms forwarding for that request. Record the client, model and test time.

The response comes back in the provider's own format, so an existing client works unchanged. This example is an Anthropic Messages response; its usage field reports input and output tokens.

response.json
{
  "id": "msg_011CgUfvZ1gRkTDnkXLqnvi6",
  "type": "message",
  "role": "assistant",
  "model": "claude-haiku-5-5",
  "content": [
    {
      "type": "text",
      "text": "An API gateway is a server that acts as a single entry point for client requests, routing them to the appropriate backend services while handling tasks like authentication, rate limiting, and load balancing."
    }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 23, "output_tokens": 59 }
}

A key that is not a Cortex key returns 401 with capture_identity_token_malformed:

unauthorized.json
{
  "error": {
    "code": "capture_identity_token_malformed",
    "message": "the API key is not a valid Cortex API key (Cortex keys start with cct_)"
  }
}

Cortex keys start with cct_. A provider key, such as one starting with sk-ant-, belongs in the provider connection, not in your client.

These examples request an explicit model. Auto Router requires managed configuration and a qualified client and request path, such as Codex using Responses. For automatic routing, follow Inspect decisions and evaluate.

Confirm the request in Cortex

  1. In Cortex, open View and select Gateway, or select Gateway in the left menu if your workspace shows it there. Then open API Keys. Admins select My Keys.
  2. Find the key you used. Last used shows when Gateway last accepted the key. If you used the key in the previous few minutes, it can show that earlier time.
  3. Admins also see Spend 30D. It is not a first-request check; it can stay at $0.00 after a successful request.

A provider response and Last used confirm that the request reached Gateway. They do not confirm that it appears in Atlas or Usage.

Troubleshoot the first request

ResultNext action
capture_identity_token_*Confirm that the personal cct_ token is current and reaches Gateway through the client's supported header. Anthropic's x-api-key alone does not carry capture identity.
unknown_modelUse an exact model ID that Gateway routes for your organization.
provider_not_configuredAdd or enable that provider's key in provider configuration, or ask your administrator to.
unsupported relay endpointCheck the client-specific URL shape. Shared Egress and endpoint Defender URLs are not interchangeable.
A response arrives but activity is missingCheck Last used for the key on API Keys first. It shows when Gateway last accepted the key, so a use in the previous few minutes can show that earlier time. If it shows no use around your request time, confirm the intended account and test time, then review Device and source coverage.
  • For response formats and policy refusals, use Errors and limits.
  • Share the client name, response status and test time with your administrator, or with support@chaoslabs.xyz if you are the administrator. Exclude tokens and private prompt text.

The Gateway product tour shows the operating screens. For deployment choices, see Shared Egress Gateway and endpoint Defender Gateway. Shared Egress uses your organization's endpoint; endpoint Defender Gateway handles qualified paths through a managed Defender installation.