Model Gateway

Preview Base URL: https://gqbzygqa4dd3t54xnb2fg5wcou0pitmm.lambda-url.us-east-1.on.aws

Overview

Model Gateway calls AI model providers for a person, with that person’s own provider API key, and counts each call against one of the person’s spend grants.

• A provider credential is the person’s API key for one provider, such as OpenAI or Anthropic. Model Gateway stores it encrypted and never returns it.
• A spend grant is the person’s consent, in Granite, for an agent to make calls with one credential. Model Gateway counts each call against the grant’s limit_units; see Concepts.
• A usage record is written for each call counted against a grant.

The provider bills the person directly for every call made with their key. Model Gateway does not take or hold payments.

A request to the public endpoints acts for one person, who has approved the caller in Granite: the caller presents that Granite grant, and the endpoint acts on the records of the person who owns it.

What preview means here: Model Gateway runs in production, but today only Stackwell’s own services use it, and the endpoint that makes model calls is not documented here. These pages document the public endpoints (provider credentials, custom adapters and usage) so you can see how the service behaves; Quickstart lists what a caller needs.

Quickstart

1. Check that Model Gateway is reachable

No credentials needed:

curl -fsS https://gqbzygqa4dd3t54xnb2fg5wcou0pitmm.lambda-url.us-east-1.on.aws/health

{"service":"model-gateway","status":"ok"}

2. See that every other call needs a credential

curl -sS https://gqbzygqa4dd3t54xnb2fg5wcou0pitmm.lambda-url.us-east-1.on.aws/v1/model-gateway/spend-usage | grep -Fx '{"error":"unauthorized"}'

What you would need to go further

To call any other endpoint, a caller needs both of these:

1. A ChirpAuth machine token. Model Gateway accepts one from any ChirpAuth client; the person’s Granite grants decide what the caller may do.
2. An approved Granite grant from the person, naming your agent and the model.gateway.call scope. See Authentication.

With both, a request looks like this:

curl https://gqbzygqa4dd3t54xnb2fg5wcou0pitmm.lambda-url.us-east-1.on.aws/v1/model-gateway/spend-usage \
  -H "Authorization: Bearer $CHIRPAUTH_MACHINE_TOKEN" \
  -H "x-user-id: u_8Q3K2M11XZ" \
  -H "x-granite-grant: b6ddef35-fe77-43be-a871-bb80d528906a"

Authentication

Every endpoint except GET /health and a diagnostics endpoint needs a ChirpAuth machine token, your id for the person in x-user-id, and the id of the person’s Granite grant in x-granite-grant. Model Gateway asks Granite whether the grant is approved for your agent, and acts for the person who owns it. People’s own sign-in tokens are refused. Authentication has the details.

API reference

The full endpoint list is in the generated API reference. API examples shows each public endpoint with real requests and responses, and Concepts explains the rules they enforce.

Conventions shared by every endpoint:

• Every path starts with /v1/model-gateway/, except /health.
• Request and response bodies are JSON; send Content-Type: application/json.
• Times are RFC 3339 in UTC. Ids are UUIDs, except a custom adapter’s, which is its name.
• Lists are not paged and come oldest first.
• There are no idempotency keys: every POST creates a new record.

Errors and limits

Errors are JSON, {"error": "<message>"}, except parsing errors, which are plain text. Model Gateway sets no rate limits of its own; request bodies are capped at 2 MiB. Errors and limits lists the status codes and field limits.

Data and privacy

Model Gateway stores a person’s provider credentials (the key encrypted), custom adapters, a count for each spend grant used, and usage records, in AWS us-east-1. It does not store prompts or model responses. Credentials and custom adapters can be deleted; counts and usage records are kept. Data and privacy says exactly what is stored, who can read it, and what deletion does.