Concepts
The AI Gateway is built around a small set of objects. This page defines each one, and the rest of the AI Gateway docs assume you're already familiar with these terms.
Access Key
The credential a client presents to the gateway itself, not to be confused with the auth token used by the SocketXP agent for device registration, local AI model provider registration, and the SocketXP API access.
An Access Key follows the format sxp_<id>_v1_<secret>. It's shown to you exactly once,
at creation time — SocketXP doesn't store the raw key, so it can't be recovered or
redisplayed afterwards. A key can either be present or deleted; there's no update or
revoke endpoint for it.
An Access Key can optionally carry an Access Key Policy. A key with no policy attached has unlimited use by default, meaning any provider and any model.
Access Key Policy
A Policy restricts what an Access Key may be used for, along two independent dimensions:
ProviderIds, the set of providers (custom, built-in, or both) the key may route to,
and ModelIds, the set of models it may request. Leaving either list empty means "allow
all" for that dimension.
A Policy applies the same way to both custom and built-in providers. It's checked against whichever provider and model the gateway resolves a given request to.
Custom Provider
A provider you register yourself, typically a self-hosted model server such as Ollama, vLLM, or LM Studio, reached through a SocketXP tunnel rather than the public internet.
| Field | Meaning |
|---|---|
Name |
Display name. |
Slug |
Unique per user; the routing token used in /v1/provider/<slug>/.... |
InternalEndpoint |
The tunnel this provider routes to. |
LocalApp |
The local application or service behind the tunnel. |
ProviderApiKey |
Optional. Set this if your own local server requires a key. |
ModelIds |
Freeform strings you define, matching whatever your server calls its models. |
A tunnel with InternalEndpoint set is private only. It isn't reachable through its
normal public <uuid>.socketxp.com subdomain, only through the AI Gateway. See
Custom Providers.
Built-in Provider
The global, public catalog of hosted providers SocketXP maintains for you: OpenAI,
Anthropic, and Google today (more to be supported in the future). Each one has a display name, a routing slug, and a set of
supported models named in the canonical provider:creator/model form, such as
openai:openai/gpt-5.6-luna.
This catalog isn't editable through the web portal or the API — SocketXP keeps it current on your behalf. See Built-in Providers.
Built-in Provider Key (BYOK)
Your own API key for one built-in provider, in other words, bring your own key.
You can register more than one key per provider, say a personal key and a team key. Routing always uses the oldest key on file for that provider; there's no per-request key selection today (will be supported in the future). Keys are shown masked, with only the last 4 characters visible, in every API response.
How these fit together
A request arrives carrying an Access Key. The gateway resolves it to your account and an
optional Policy, resolves the request's model field to either an AI Provider (custom)
or an AI Public Provider (built-in), checks the Policy against that resolution, and, for
built-in providers, looks up the matching BYOK key to forward the request with.