Spend Gateway

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

Overview

Spend Gateway records how much an app may spend on a person’s behalf, and what it has spent.

1. The person creates a spend grant that lets one app draw on their behalf. Concepts says what limits a draw.
2. When a Stackwell service does metered work for that app, such as a Compute Gateway run, the service reserves units against the grant before it starts and settles the units actually used when it finishes.
3. The person can read each grant’s balance and the settled usage, and revoke a grant at any time.

Spend Gateway counts in abstract units. The service that does the work decides how many units it costs.

Spend Gateway takes no payments. A person or developer has no way to add balance to a wallet; only Stackwell can. See Wallets.

What preview means here: Spend Gateway runs in production, and Stackwell’s own services call it. An outside developer cannot use it today. It accepts tokens only from ChirpAuth clients it is configured to accept, all of them Stackwell’s own, and there is no way to request access yet. These pages describe what the running service does, so you can see how it works before it opens.

Quickstart

1. Check that Spend Gateway is reachable

No credentials needed:

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

{"service":"spend","status":"ok"}

2. What you need before you can do more

Every other call needs a ChirpAuth token from a client Spend Gateway accepts. You cannot get one today: Spend Gateway accepts only Stackwell’s own ChirpAuth clients, and there is no sign-up.

Without one, every call is refused:

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

3. What a first call looks like

With an accepted token, a caller lists its own grants:

curl https://fwkl7sygagsdlb6ut3lsomjmvi0qvyyt.lambda-url.us-east-1.on.aws/v1/spend/grants \
  -H "Authorization: Bearer $SPEND_TOKEN"

A caller with no grants gets 200 OK and []. API examples walks through creating a grant, reading its balance and usage, and revoking it.

Authentication

Every call except GET /health and a diagnostics endpoint sends Authorization: Bearer <token>, where the token is one of:

• The caller is the owner. Spend Gateway takes the owner from the token’s subject (sub). No header or body field names a different owner, so a caller can only create, read, change or revoke its own grants.
• No scopes. An accepted token can make every call on this page.
• Refusals don’t say why. A missing, expired or unaccepted token gets 401 with {"error":"unauthorized"}.

Not yet: there is no way for an outside developer or app to get an accepted token.

API reference

The full endpoint list is in the generated API reference. API examples shows each endpoint with real requests and responses, and Concepts explains grants, balances and usage.

Conventions shared by every endpoint:

• Base URL https://fwkl7sygagsdlb6ut3lsomjmvi0qvyyt.lambda-url.us-east-1.on.aws; paths start with /v1/spend/.
• Request and response bodies are JSON; send Content-Type: application/json.
• Units are whole numbers (0 or more). Ids are UUIDs. Times are RFC 3339 in UTC.
• Lists are not paged.

Errors and limits

Errors are JSON, {"error": "<message>"}, except request-parsing errors (a bad path id, malformed JSON, a missing field, a wrong content type), which are plain text. Spend Gateway has no rate limits of its own; request bodies are capped at 2 MB. Errors and limits lists every status code.

Data and privacy

Spend Gateway stores each owner’s grants, wallet balance and settled usage, keyed by the subject id in their ChirpAuth token. It learns no name or email address. It deletes nothing: revoked grants and usage are kept, and there is no way yet for a person to delete their data. Data and privacy has the details.