​

Gas City Service Protocol v0

​

What this is

gc login                                  # → the default, https://gascity.com
gc login --at https://gc.mycorp.example   # → a self-hosted conforming server

​

1. Base URL and endpoint resolution

1. the explicit --at <url> flag value;
2. the GC_SERVICE_URL environment variable;
3. the stored default in the client credential file (the last URL logged into);
4. the compiled-in default constant https://gascity.com.

​

2. Versioning

• The version string for this revision is gascity.dev/service/v0.
• Every request from a conforming client SHOULD send X-GC-Service-Version: gascity.dev/service/v0. A server MAY use it to route or to reject an unsupported client with 426 Upgrade Required.
• Paths are namespaced under the versioned prefix /gc/v0/. A future incompatible revision uses a new prefix (/gc/v1/) and a new version string; the two can be served side by side.

​

3. Endpoints (auth + identity)

​

3.1 Browser-callback login — GET /gc/v0/auth/cli

GET {base}/gc/v0/auth/cli?redirect_uri={loopback}/callback&state={state}&label={label}

• redirect_uri — the CLI’s loopback callback (http://127.0.0.1:<port>/callback).
• state — an opaque, unguessable CSRF value the CLI generates and later verifies.
• label — a human label for the minted token (e.g. user@host), for display on the account’s token list.

POST http://127.0.0.1:<port>/token
Content-Type: application/json

{ "token": "<opaque-bearer>", "service": "{base}", "state": "{state}" }

• rejects the delivery unless state matches the value it generated;
• rejects it unless service is present and equals the login target — a callback that omits or mismatches service is refused, so a stray or hostile callback can never redirect the token to a different service. (service is therefore REQUIRED in the fragment.)
• stores token and returns.

​

3.2 Device-code login — POST /gc/v0/auth/device/{code,token}

{ "label": "user@host" }

{
  "device_code": "<opaque>",
  "user_code": "BDWK-JQPX",
  "verification_uri": "https://gascity.com/gc/v0/device",
  "verification_uri_complete": "https://gascity.com/gc/v0/device?code=BDWK-JQPX",
  "expires_in": 900,
  "interval": 5
}

{ "device_code": "<opaque>" }

• On success 200: { "access_token": "<opaque-bearer>", "token_type": "bearer" }.
• While pending, respond with a non-2xx status and a body carrying an error:
  • authorization_pending — keep polling at the current interval;
  • slow_down — increase the interval (to the returned interval if present, else by a fixed step);
  • access_denied — the user rejected; stop with an error;
  • expired_token — the code expired; stop with an error.

​

3.3 Identity — GET /gc/v0/me

GET {base}/gc/v0/me
Authorization: Bearer <token>

{
  "user": { "id": "<opaque>", "handle": "julian", "display_name": "Julian K." },
  "session": { "created_at": "…Z", "expires_at": "…Z", "last_used": "…Z", "fingerprint": "gcs_ab" },
  "message": "You have $5 of trial credit.",
  "links": { "account": "https://gascity.com/account" }
}

• user.id — a stable opaque account identifier. There is no org or tenant field. An account is addressed only by opaque id/handle; the wire carries no tenancy identity.
• session — optional, display-only metadata (created_at, expires_at, last_used, fingerprint) the CLI shows via gc whoami so a user can see when the session expires and correlate it with the account’s session list. The client never parses the token; fingerprint is a short non-secret label, never the handle.
• message / links — optional, server-authored, printed verbatim by the CLI (see §5).

​

3.4 Logout — DELETE /gc/v0/session

DELETE {base}/gc/v0/session
Authorization: Bearer <token>

​

4. Client credential storage

{
  "default_service_url": "https://gascity.com",
  "services": {
    "https://gascity.com": { "token": "<opaque>", "updated_at": "2026-07-10T…Z" }
  }
}

​

5. The opacity rule

• Human-facing policy copy travels as opaque message strings.
• Actionable destinations travel as opaque links URLs the CLI may open.
• The token is an opaque bearer.

​

6. Errors

{ "error": { "code": "invalid_token", "message": "Session expired." } }

• invalid_token — the session is missing, expired, or invalid (re-login).
• forbidden / insufficient_scope — authenticated but not permitted for this action (do not re-login; surface message).

​

7. The session token, and 401 vs 403

• 401 (or error.code = invalid_token) → the session is invalid/expired → “not logged in; run gc login”.
• 403 (forbidden / insufficient_scope) → authenticated but not permitted → print the server message verbatim; do not advise re-login.
• 5xx → a server-side failure → retryable; do not advise re-login.

​

8. Discovery (optional, forward-compatible)

GET {base}/.well-known/gascity-service
→ 200 { "version": "gascity.dev/service/v0",
        "endpoints": { "auth_cli": "/gc/v0/auth/cli", "device_code": "…",
                       "device_token": "…", "device_verify": "/gc/v0/device",
                       "me": "/gc/v0/me" },
        "message": "…" }

​

9. Reserved surface

• Cities — POST /gc/v0/cities, GET /gc/v0/cities/{id}: provision and watch a hosted city (the gc init --at flow).
• Runs — POST /gc/v0/runs, GET /gc/v0/runs/{id}, GET /gc/v0/runs/{id}/events, POST /gc/v0/runs/{id}/claim: submit and watch a formula run, optionally anonymously (the gc run --at flow).
• Scoped-token challenge — a 401 MAY carry a standard RFC 6750 WWW-Authenticate: Bearer realm="…", scope="example:resource.action" challenge naming a token endpoint from which a client fetches a short-lived, scoped credential (the docker login model, for a future client that holds its own scoped tokens). A v0 client ignores the challenge and reports not-logged-in per §7. When implemented: the realm is trusted only if same-origin with the login base URL or named by the login origin’s discovery document (§8, via a token_endpoint field); the session bearer is sent only to the login origin; scopes are opaque strings the client echoes verbatim.
• Session rotation — a server MAY return a replacement session handle in a response header on an authenticated response; a client that supports rotation atomically re-stores it (a pure string swap — no parsing) and treats reuse of a superseded handle as the server’s cue to re-login. v0 clients ignore the header. Reserved so the header name can be fixed without a breaking change; rotation buys server-side theft detection without proof-of-possession.

​

10. Server conformance checklist (for gc login)

1. serves an interactive sign-in page at GET /gc/v0/auth/cli that redirects to redirect_uri with token, service, and state in the URL fragment;
2. implements the device-code pair at POST /gc/v0/auth/device/{code,token} with the RFC-8628-shaped fields and error values above;
3. serves the device verification page at GET /gc/v0/device and accepts its approve/deny form at POST /gc/v0/device for an authenticated browser;
4. implements GET /gc/v0/me returning { user: { id, handle, display_name } } for a valid bearer and a non-2xx for an invalid one;
5. treats the token as an opaque bearer it can validate;
6. confines all account/commercial policy behind these endpoints, exposing it to the client only through opaque message/links.