Gateway quickstart

Two minutes from zero to a governed call. In Python, use the first-party egisai client — one import, zero wiring. From any other language, call the API directly (or point any OpenAI-compatible client at the Gateway).

Prerequisites

An EgisAI account on a plan with the Gateway enabled.

An Egis API key (Dashboard → API Keys → Create key). Keys begin with egis_live_.

A provider API key — OpenAI in the snippets below; Anthropic (claude-… models) and Google (gemini-… models) work the same way, since the Gateway routes by model name.

1. Connect

Your provider key stays exactly where it always was — in the Authorization header — and is forwarded to the provider untouched. Your Egis key rides in X-Egis-Api-Key (egisai.Client sets both for you).

# pip install "egisai[openai]" — one import, no provider SDK in your
# code, no base_url or header wiring.
import egisai

client = egisai.Client(
    api_key="egis_live_…",   # your Egis key
    provider_key="sk-…",     # your provider key, forwarded untouched
)

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "Hello through the Gateway!"}],
)
print(response.choices[0].message.content)

# Bring-your-own client: any OpenAI-compatible client works — change
# the base_url and add the X-Egis-Api-Key header.
from openai import OpenAI

client = OpenAI(
    api_key="sk-…",  # your OpenAI key, forwarded untouched
    base_url="https://app.egisai.co/v1/agent",
    default_headers={"X-Egis-Api-Key": "egis_live_…"},
)

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "Hello through the Gateway!"}],
)
print(response.choices[0].message.content)

// Plain fetch — no extra dependency needed.
const response = await fetch("https://app.egisai.co/v1/agent/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-…",
    "X-Egis-Api-Key": "egis_live_…",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-4.1",
    messages: [{ role: "user", content: "Hello through the Gateway!" }],
  }),
});

const completion = await response.json();
console.log(completion.choices[0].message.content);

curl https://app.egisai.co/v1/agent/chat/completions \
  -H "Authorization: Bearer sk-…" \
  -H "X-Egis-Api-Key: egis_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [{"role": "user", "content": "Hello through the Gateway!"}]
  }'

The dashboard’s Gateway page (under Developers) has copyable snippets for more languages — Go, Java, C#/.NET, PHP, Ruby — all plain HTTP calls with no third-party dependency.

Both keys are secrets. Use environment variables or a secrets manager — never hardcode them as in these snippets.

Connect without custom headers (BYOK vault)

Some platforms — Cursor, n8n, low-code builders — only let you set a base URL and an API key. They can’t add the X-Egis-Api-Key header. For those, store your provider keys once and connect with only your Egis key:

Store your provider keys

On the dashboard’s Model Center page, open Provider keys and add the key for each provider you use (OpenAI, Anthropic, …) — one per provider. They’re encrypted at rest; we keep only the last four characters for display. (Owners and admins only.)

Point the platform at the Gateway

Set the base URL to https://app.egisai.co/v1/agent and the API key to your Egis key (egis_live_…). That’s it — no headers.

import egisai

# No provider_key — the Gateway uses your stored key.
client = egisai.Client(api_key="egis_live_…")

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "Hello through the Gateway!"}],
)

from openai import OpenAI

# The Egis key goes in api_key (it rides in Authorization); no
# X-Egis-Api-Key header, no provider key.
client = OpenAI(
    api_key="egis_live_…",
    base_url="https://app.egisai.co/v1/agent",
)

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "Hello through the Gateway!"}],
)

curl https://app.egisai.co/v1/agent/chat/completions \
  -H "Authorization: Bearer egis_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [{"role": "user", "content": "Hello through the Gateway!"}]
  }'

The Gateway routes by model name, so one stored key per provider covers every model from that provider. If no key is stored for the request’s provider, the call returns an OpenAI-shaped error with code: "egis_no_provider_key" telling you which provider to configure.

2. See the call on the dashboard

Open the Requests page. Your call appears within seconds, marked with a gateway channel icon. The Gateway page (under Developers) also shows a live “last call received” status — useful for confirming connectivity during setup.

3. Watch a policy fire

Create a policy on the Policies page — for example, a PII scan set to sanitize on the Request phase — then send a prompt containing a fake SSN:

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "My SSN is 123-45-6789."}],
)

The SSN is masked before the payload leaves the Gateway; the provider sees only the masked text, and the audit row records the sanitization (count and mask shape — never the original value). A block verdict on the request phase returns an OpenAI-shaped error with code: "egis_policy_blocked" and HTTP 400 — the provider is never called, and no tokens are spent.

Naming your agent

By default the Gateway derives agent identity from the system prompt, so distinct system prompts appear as distinct agents automatically. To name an agent explicitly with egisai.Client:

client = egisai.Client(
    api_key="egis_live_…",
    provider_key="sk-…",
    agent="support-triage-bot",
)

From other languages (or a bring-your-own client), the same thing is one more header:

-H "X-Egis-Agent: support-triage-bot"

And when egisai.init() is active, the usual context API sets the header per call — it wins over the client-level default:

egisai.set_context(agent="support-triage-bot")   # → X-Egis-Agent

The rest of the set_context fields travel the same way, so the run’s Context section fills in exactly like it does for SDK-audited traffic:

egisai.set_context(
    user_id="support-ops-1042",       # → X-Egis-User
    user_role="support_engineer",     # → X-Egis-User-Role
    session_id="sess-8f3a",           # → X-Egis-Session
    workflow_id="wf-refund-42",       # → X-Egis-Workflow
    end_user_id=hashed_customer_id,   # → X-Egis-End-User (re-hashed on intake)
)

What’s next

Streaming

How stream: true interacts with response-phase policies.

Limits & behavior

Error shapes, failure modes, and current limitations.

Get started

Core concepts

Integrations

Gateway

Coverage

Guides

Operations

Gateway quickstart

Prerequisites

1. Connect

Connect without custom headers (BYOK vault)

2. See the call on the dashboard

3. Watch a policy fire

Naming your agent

What’s next

Streaming

Limits & behavior

​Prerequisites

​1. Connect

​Connect without custom headers (BYOK vault)

​2. See the call on the dashboard

​3. Watch a policy fire

​Naming your agent

​What’s next

Streaming

Limits & behavior

Prerequisites

1. Connect

Connect without custom headers (BYOK vault)

2. See the call on the dashboard

3. Watch a policy fire

Naming your agent

What’s next