Tenants and keys

Add a tenant and a key

1. 1

   Add the tenant

   On Tenants, choose Add tenant. Give it a name, and optionally a fairshare group and weight.

2. 2

   Make a key

   On the tenant's page, choose New key (or use New key on API keys and pick the tenant). The secret is shown once, in a banner with Copy and Copy as OPENAI_API_KEY=…. The gateway keeps only a hash of it.

3. 3

   Call the gateway

   Clients send the key as Authorization: Bearer sk_… or as x-api-key: sk_…, the header Anthropic SDKs use. See OpenAI-compatible API.

The same through the Management API:

curl -X POST http://localhost:9180/api/v1/tenants \
  -H "Authorization: Bearer $OBLETH_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "genomics-lab", "fairshare_group": "research", "weight": 200}'

curl -X POST http://localhost:9180/api/v1/tenants/$TENANT_ID/keys \
  -H "Authorization: Bearer $OBLETH_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "variant-pipeline"}'
# {"key": {...}, "secret": "sk_..."}

Tenants

A tenant is the unit fairshare divides between: every key belongs to exactly one tenant, and a tenant's weight sets its share of each model's pool against the other tenants in its group. See How fairshare works.

Tenants lists every tenant with its group and weight, keys, users, requests in the last day, spend against its budget, limits, and whether its access hours are open now. Filter by status, group, or what a tenant has set, such as a budget, access hours, a model list, guardrails, or being near a limit.

Each tenant has its own page at /tenants/<name>: requests and failures in the last day, its budget and where the current pace lands, running requests against fair share, a 30-day chart, its limits right now, the models it uses, its keys and people, and recent changes.

Below that, every setting sits on one page with Find a setting (⌘K) and one save bar:

The status menu in the header sets the tenant to active, suspended or archived. Suspended and archived tenants are refused with 403.

Fairshare groups

A group is a set of tenants that share one weight: a department, or all teaching tenants against all research tenants. Each pool is split between active groups by group weight first, then between each group's tenants. Every tenant is in the default group until you move it.

Change group weights on Fairshare › Groups & weights, which previews every group's new share before you save. Change a tenant's group on its page. Through the API:

curl -X POST http://localhost:9180/api/v1/fairshare/groups \
  -H "Authorization: Bearer $OBLETH_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "research", "weight": 300}'

curl -X PATCH http://localhost:9180/api/v1/tenants/$TENANT_ID/group \
  -H "Authorization: Bearer $OBLETH_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"fairshare_group": "research"}'

Groups apply under the default hierarchical algorithm. With OBLETH_FAIRSHARE_ALGORITHM=weighted, all tenants compete directly and groups are ignored.

Keys

Give each person, application or pipeline its own key. All of a tenant's keys share its limits, budget and model list, and each key can also carry:

API keys shows every key with its tenant, status, last use, 30-day requests and spend, budget for the current period, and weight. Tiles count keys used today, near a budget, and unused for 30 days.

Open a key for its 30-day use, its settings with a save bar, and Replace…, Move… and Delete…. Replace… makes a new key with the same settings; the old one keeps working until you turn it off. Select several keys to turn them off or on, give them one budget, move, export or delete them together.

Turning a key off takes effect on every gateway on its next request; the key returns 403 api key disabled. A deleted key returns 401.

Move keys to another tenant

Move… takes keys to another tenant, or to a new tenant made for them. A new tenant can copy the source tenant's weight, group, limits, hours, budget, models and policies. This gives a heavy user a share of their own without handing out a new secret. Past usage stays with the tenant it was recorded under.

curl -X PUT http://localhost:9180/api/v1/keys/$KEY_ID/tenant \
  -H "Authorization: Bearer $OBLETH_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"tenant_id": "'"$NEW_TENANT_ID"'"}'

Portal users

People who sign in with SSO can manage their own tenant's keys without dashboard access. On Users, give the account the user role and link it to a tenant. They land in the portal, which has three pages:

See Sign-in and SSO.

curl -X PUT http://localhost:9180/api/v1/keys/$KEY_ID \
  -H "Authorization: Bearer $OBLETH_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "ci", "weight": 200, "max_in_flight": 4, "budget_cost_usd": 25, "budget_period": "monthly"}'