Authentication

Model Gateway accepts one kind of caller: an agent or service holding a ChirpAuth machine token, acting for a person who approved it in Granite.

It accepts a machine token from any ChirpAuth client. What the caller may do is decided by the person’s Granite grants, not by which client it is. Today only Stackwell’s own services use it.

The headers

Authorization: Bearer <ChirpAuth machine token>
x-user-id: u_8Q3K2M11XZ
x-granite-grant: b6ddef35-fe77-43be-a871-bb80d528906a

For every request except the public ones, Model Gateway:

1. Verifies the token with ChirpAuth. It must be a machine token. A missing or invalid token gets 401. A person’s sign-in token is refused too (401 or 403).
2. Reads x-user-id, your own id for the person (1 to 128 characters, no control characters). Missing, it gets 401. Model Gateway passes it to Granite and does not otherwise trust it.
3. Reads x-granite-grant, the id of the person’s Granite grant. Missing or not a UUID, it gets 403.
4. Asks Granite whether that grant is approved for your agent: active, for resource model-gateway and scope model.gateway.call, with your token’s ChirpAuth subject as its agent. If Granite does not approve it, the request gets 403. If Granite can’t be reached, it gets 503.
5. Acts for the person who owns the grant. Their Granite id is the owner_uid on every record.

Granite’s checks are the ones described in Granite’s own documentation. The person creates the grant by approving a Granite request with request_type capability_grant, requested_resource model-gateway, requested_scopes ["model.gateway.call"], and your agent’s ChirpAuth subject in requester_chirp_sub.

Model Gateway checks the grant on every request. If the person revokes it in Granite, the next request gets 403.

What a caller may do

A caller with an approved grant may do everything on the public endpoints for that person: create, list and delete provider credentials and custom adapters, and list usage. These credentials carry no finer scopes. A model call also needs the person’s spend grant.

No credential

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

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