# Weirgate full agent documentation API version: 2026-07-18 # Authentication and scoped grants Management requests use `X-Admin-Key: `. Store the value in an OS keychain or environment variable and pass only its reference to MCP configuration. Never commit a literal key. `weirgate auth login` opens `https://dashboard.weirgate.com/consent` by default. The signed-in developer reviews tenant, apps, tool groups, scope, environment, and expiry; the CLI exchanges the resulting single-use localhost callback code and stores the reveal-once bounded key in macOS Keychain. Propose is the default. Apply consent requires a recent Clerk second factor. `--stdin` remains available for an already-minted key. Scopes are hierarchical: `read < propose < apply`. Resource bounds are independent: `app_ids`, `tool_groups`, and `environment` further constrain the key. A propose key can create and cancel its own pending proposals, but applying a proposal or creating a grant requires apply scope. Cross-tenant and out-of-bound app reads return `resource_not_found`. The platform super-admin credential is for founder operations only. It is not accepted by the MCP server or CLI authentication workflow. `GET /v1/admin/auth-presets` returns non-secret templates for Firebase, Supabase, Clerk, and custom public OIDC/JWKS issuers. Standards-based configs use `mode: jwks` with an HTTPS issuer, public HTTPS JWKS URL, optional audience, and an external-ID claim that defaults to `sub`. Service-role secrets are never accepted. # BYOK and Connect OpenRouter Connect OpenRouter is the preferred user-funded path. The end user completes OpenRouter's connection ceremony, and the application passes the resulting ephemeral credential only on the inference request. User-funded traffic is accepted only for features whose server-owned `key_policy` allows it. The application still sends the stable feature ID; it cannot use a user credential to choose a different provider, model, or output ceiling. Weirgate never stores or logs `X-User-Provider-Key`. A user-funded request settles zero Weirgate units and attributes zero provider cost to the app owner while retaining non-content operational metering with `key_source=user`, token counts, and latency. Developer-funded features reject a user-key header so callers cannot evade the application's allowance policy. Provider availability is exposed by the authenticated feature catalog and evaluated before reserve. Raw direct-provider user-key routes are not the public path. OpenAI, Anthropic, Google, and xAI credentials must not be pasted into the application for direct routing. # CLI integration The `weirgate` CLI exposes the same scoped public workflows as MCP with stable JSON, table, and YAML output. ```sh weirgate auth login weirgate auth status --output json weirgate init --app my-app --output json ``` Browser login is the default. The dashboard consent screen shows the tenant, apps, tool groups, scope, environment, and expiry before issuing a single-use callback code. The CLI exchanges it and stores the reveal-once grant in macOS Keychain. `--stdin` accepts an already-minted key when browser login is unavailable. Use `--dry-run` before apply, grant, or reversal operations and always pass a stable `--idempotency-key` for the real mutation. Config and rules changes remain durable proposals; a stale proposal must be rebased and previewed again. Provider-key put and rotate default to a local browser ceremony. Hidden `--stdin` is available, but piped secret input is rejected unless the human explicitly opts in with `--allow-pipe`. Key values never appear in JSON output. Run `weirgate completion zsh` or `weirgate completion bash` for shell completion. Set `WEIRGATE_API_URL` only when deliberately targeting a non-production environment. # Typed errors and recovery Every failure includes `X-Weirgate-Error-Type`, `X-Weirgate-Request-Id`, and `Weirgate-Api-Version`. Branch on the error type, never on message text. Preserve the request ID in support output while excluding credentials and content. Common recovery classes are validation (`invalid_request`), authentication and scope (`invalid_token`, `insufficient_scope`), missing resources, stale proposals, provider or policy blocks, and internal failures. The CLI maps these classes to stable exit codes so scripts can retry, request human approval, or stop safely. # Apps, features, tiers, and rules An app has an authentication contract, a default tier, allowance-bearing tiers, and feature contracts. A feature owns modality, provider routing, model, output contract, unit cost, key policy, enabled state, and mock/live mode. Application callers select only the stable feature ID; client-supplied model and token ceilings are overridden. Config changes are durable proposals bound to the current tenant revision. Rules changes also require preview evidence over a completed lookback window. Applying a stale proposal fails with `proposal_stale`; fetch current config, rebase the intended change, and propose again. # MCP integration The hosted MCP server is `https://mcp.weirgate.com/mcp`. It is an independent HTTPS client of the public management API, not a privileged path into Weirgate. Start from a dashboard-issued grant. Choose the tenant, test environment, app allowlist, tool groups, expiry, and scope in the consent screen. Propose is the safe default. Store only the environment-variable reference in MCP configuration: ```toml [mcp_servers.weirgate] url = "https://mcp.weirgate.com/mcp" bearer_token_env_var = "WEIRGATE_API_KEY" ``` Begin with `weirgate_whoami`, search the canonical docs, then inspect apps and readiness. Use proposals for app, feature, tier, rule, and webhook changes. Present the server's diff and pause for human approval before any apply. Grants and reversals are immediate money actions and require an apply-scoped grant plus a stable idempotency key. MCP has no generic HTTP, SQL, provider-key value, management-key mint, destructive deletion, or live-inference tool. Provider credentials enter only through the local CLI browser or hidden-stdin ceremony. Every result carries the upstream `request_id` and `api_version`. Branch on typed error values, never message strings. # The eight-minute quickstart The shortest safe path ends with a customer-owned mock call. It does not require a provider key, spend money, or promote a feature to live. 1. **Minute 0–1 — sign in.** Run `weirgate auth login`. Review the tenant, test environment, app bounds, tool groups, expiry, and propose scope in the browser. The CLI stores the reveal-once grant in macOS Keychain. 2. **Minute 1–2 — inspect.** Run `weirgate auth status`, list visible apps, and read readiness for the target app. MCP users start with `weirgate_whoami`. 3. **Minute 2–4 — propose.** Define the app authentication contract, tiers, and mock features against the current config revision. A feature owns routing, model, output ceiling, unit cost, and key policy; callers select only its stable feature ID. 4. **Minute 4–5 — review and apply.** Read the proposal diff, validation, impact, base revision, and expiry. A human applies it with an apply-scoped test grant. Never bypass the proposal workflow. 5. **Minute 5–6 — prove the control plane.** Run the explicit auth doctor check and the deterministic `success` sandbox fixture. Rehearse the typed-error fixtures relevant to the integration. 6. **Minute 6–7 — wire the request.** Obtain the generated HTTP snippet or use an official SDK. Supply a fresh end-user JWT, `X-App-Id`, stable `X-Feature-Id`, and a per-action `X-Idempotency-Key`. 7. **Minute 7–8 — make the app-owned mock call.** Send it from the integrating app, retain the request ID, then read usage, the user timeline, readiness, and audit attribution. 8. **After the timer — promote deliberately.** Enter provider credentials only through the local browser or hidden-stdin ceremony, rerun doctor, and use a separate reviewed proposal to move the feature to live. `weirgate init --app ` orchestrates the public readiness steps; it is not a privileged shortcut. Config propagation can take up to 30 seconds, so retry a typed `resource_not_found` within that documented window instead of changing the proposal. Do not promote a feature until mock success and the required typed-error fixtures pass. # Usage, grants, audit, and doctor Usage queries return request, unit, token, provider-cost, user-cost, and latency rollups for an explicit UTC window. Pricing insights accept only closed UTC-midnight periods and include completeness and sample-suppression metadata. Grants and reversals are immediate apply-scoped money actions and require an idempotency key. Rules should be previewed before proposal. Doctor probes are non-billable and accept only explicit auth, provider, or webhook checks. Audit queries attribute proposals, applies, grants, reversals, and sensitive metadata reads to a management-key ID. # Weirgate overview Weirgate is a BYOK LLM middle tier for consumer applications. Applications choose a stable `X-Feature-Id`; Weirgate owns provider routing, output ceilings, metering, allowances, and operational policy. The current public contract is frozen at `Weirgate-Api-Version: 2026-07-18`. Management clients authenticate with a minted `wgk_` key over HTTPS. A key is bound to one tenant, an app allowlist, a `read`, `propose`, or `apply` scope, tool groups, an environment, and an optional expiry. Coding agents should use propose-only test grants. Provider-key values, webhook signing secrets, end-user tokens, prompts, and responses must never enter agent context, logs, committed files, or tool results. # Sandbox and mock proof Sandbox is mock by default and non-billable. It exercises the real public control path without sending prompts to a model provider. Create a named sandbox session for the target app, then run the deterministic `success` fixture and the typed-error fixtures relevant to the integration. The success case uses the real reserve-and-settle ledger at zero units and zero provider cost; error rehearsals do not enter billing. Use explicit doctor checks for authentication, provider metadata, and webhook endpoints. Doctor accepts only a check list and never a token or secret value. It is a metadata probe, not live inference. After mock proof, read readiness and generate the HTTP integration snippet. The final `send_first_call` step belongs to the integrating app because Weirgate deliberately has no live-inference MCP tool. Preserve that call's request ID and verify the joined usage, timeline, trace, and audit evidence. Promotion to live is a separate reviewed config proposal. A sandbox pass never changes a feature's mode automatically. # TypeScript and Swift SDKs The official SDKs consume only the frozen public API. They do not import server internals, connect to Weirgate's database, or persist end-user provider keys. ## TypeScript Install `@weirgate/sdk`, then provide the app ID and an async source of fresh end-user JWTs: ```ts import { Weirgate } from "@weirgate/sdk"; const client = new Weirgate({ appId: "my-app", token: async () => getFreshEndUserJWT(), }); const catalog = await client.features(); ``` Mutations receive an automatic idempotency key. Failures are `WeirgateError` values keyed by `error.type`; results and errors carry request and API-version correlation. ## Swift Add `https://github.com/weirgate/weirgate-sdk.git` in Swift Package Manager and select the `WeirgateKit` product: ```swift import WeirgateKit let client = WeirgateClient( configuration: .init(appID: "my-app"), tokenProvider: .init { try await auth.freshIDToken() } ) let catalog = try await client.features() ``` `UserProviderKey` is accepted per call, uses an ephemeral URL session with no URL cache, and is redacted from descriptions. Stream iterators verify final usage and termination. # Agent security boundaries The agent surface exposes curated workflows only. There is no generic SQL, HTTP, or API execute tool; no live inference tool; no management-key mint or escalation tool; and no provider-key value input or output. Destructive tenant and app deletion are also absent. The MCP Worker is an independent HTTPS client of `api.weirgate.com`. It has no database binding and imports no API Worker internals. Its outage cannot affect the data plane. Every tool result includes the upstream request ID and frozen API version. # Webhooks Agents propose webhook endpoint changes; an apply-scoped human or automation applies the durable proposal. Endpoint URLs must be HTTPS and pass server-side SSRF validation. Signing secrets are server-minted, reveal-once values and are never present in MCP inputs or results. Consumers verify HMAC-SHA256 over `.` before parsing. Use the event ID for deduplication. Delivery is at least once, retries use exponential backoff, ordering is best effort per user, and deliveries dead-letter after eight attempts.