# Team gateway

## Roles and credentials

One deployment represents one team. The first user is the owner. Owners manage administrator roles; administrators manage members, shared connections and allowances. Members can manage their own keys and inspect their own usage. A deployment must retain at least one active owner.

Invites are available when `INVITES=1`. Only administrators issue or revoke them. An invite creates a new member and cannot sign in an existing account. The invited member sets a first password from Settings.

With `EARLY_ACCESS=1` the public pages carry an Early access button leading to `/early-access`, where the invited person enters their email and the code instead of being sent a console URL. The accept is the same one: the code works once, for that email only, and the member sets a first password on the page it opens.

New team API keys are random credentials issued locally, with only a hash and display prefix stored. Connection credentials are encrypted under `KEYS_SECRET`. Neither stored provider credentials nor another member's keys are returned to ordinary members.

## Policies

Policies can constrain provider IDs, exact namespaced model IDs, daily token allowance, requests per minute, concurrent requests and maximum output tokens. A null permission list means unrestricted at that level; an empty list permits none. The key's permission and the member's permission must both allow a request. A member cannot expand the permissions set by an administrator.

The member allowance applies across every key and connection used by that member. An optional key allowance adds a tighter limit. Daily windows use UTC; rate windows use the preceding minute. Connection rotation stays within the resolved provider/model and does not retry a failed request automatically.

## Reservation accounting

The gateway uses a SQLite transaction to reserve input/output capacity and a concurrency slot before making a network request. This prevents concurrent requests from all spending the same remaining allowance. It rechecks key and member state after route resolution, including key rotation and policy changes.

The input reservation is the UTF-8 request size plus protocol overhead; output is capped. This deliberately overestimates ordinary text, but is not a trusted tokenizer for every provider. Provider-specific hidden work can exceed the estimate. Measured usage is charged when available; unknown or interrupted requests keep their full reservation. Finite budgets reject remote media and server-stored conversation references whose input work cannot be bounded.

Allowances are admission controls, not a mathematically guaranteed provider spend cap. The application does not translate a vendor's subscription percentage into a promised number of tokens. Rate, concurrency and output controls supplement token allowances.

## Deployment boundaries

Run one gateway process per data directory. Startup recovers abandoned reservations conservatively. Shared admission across independently running replicas is not implemented. Persistent WebSocket generations are refused until they can use the same request-level controls as HTTP and SSE.

Every public inference request must go through Jatevo. Keep provider-management and optional engine ports private. The nginx sample proxies to the gateway rather than directly to an engine. TLS is required for remote team access; secure session cookies follow `PUBLIC_BASE`.

The current release provides roles, API-key management, usage and local deployment. SAML/OIDC SSO, SCIM, high availability, billing guarantees and compliance certifications are not implemented or claimed. Define operational commitments separately for your deployment.