Auth Modes

Model dispatch requires a credential: either you supply your own API key, the platform supplies a managed key, or your worker runs locally. Rensei supports five auth modes to cover these patterns.

A model profile now carries a set of auth modes (auth_modes: AuthMode[]) rather than a single scalar. At dispatch time the resolver picks exactly one concrete mode from that set, intersected with what the org and project scope allow. The single resolved scalar is what the donmai worker sees - the set-based logic is a platform concept only.

Auth modes overview

Set-based resolution

When a dispatch fires, the resolver does the following:

Step 1 - compute effective allowed modes

The Model Access Matrix at system, org, and project scope is cascaded. Each scope may only narrow (not broaden) what the parent allows. The result is an effectiveAllowedModes set for this (org, project, model, provider) combination.

Step 2 - intersect with profile set

intersection = profile.auth_modes ∩ effectiveAllowedModes

If the intersection is empty, dispatch throws AUTHMODES_UNSATISFIABLE immediately - no fallback.

Step 3 - pick one mode by preference order

From the intersection, the resolver picks the first mode in this immutable preference order:

byok > metered > shared > host-session > local

This order is fixed and append-only. Reordering it would be a behavioral migration.

Example: Profile auth_modes: ["byok", "metered"] + org allows {metered, shared} → intersection is {metered} → resolved mode is metered.

Step 4 - resolve credential

For byok, credentialId = profile.credentials["byok"]. For all other modes, credentials are resolved platform-side (no profile-level entry needed).

Step 5 - fail-closed access gate

After buildResolved() returns, enforceAccessPolicyGate() checks that the resolved auth mode is not explicitly denied by the effective matrix (allowed !== false). If it is denied, dispatch throws AccessDeniedError. System-scope dispatches are always allowed (system scope is the cascade root).

Scope narrowing

Each scope in the org hierarchy can only narrow (subtract) what the parent allows. It cannot re-open a mode the parent denied.

System: byok ✓  metered ✓  shared ✓  local ✓  host-session ✓
          ↓ org may only subtract
Org:    byok ✓  metered ✓  shared ✗  local ✓  host-session ✗
          ↓ project may only subtract further
Project: byok ✓  metered ✗  shared ✗  local ✓  host-session ✗

In this example, a profile with auth_modes: ["byok", "metered"] dispatched under this project would resolve to byok (metered is disallowed at project scope).

For details on setting scope policies, see Model Access Matrix.

BYOK (Bring Your Own Key)

The org supplies an API key. It is stored in the credentials table, referenced by the profile's credentials.byok field.

When to use:

• You have an existing relationship with a provider and want to control spend directly.
• You need strict cost isolation (your bill, not platform's).
• You're running on restricted networks.

Setup:

1. In Settings → Integrations, click Add Provider.
2. Select the provider (Anthropic, OpenAI, Gemini, etc.).
3. Paste your API key. Rensei encrypts it immediately.
4. Click Test Connection to validate.
5. Create a model profile and ensure byok is in auth_modes. Set the credentials.byok entry to the new credential ID.

Execution: BYOK profiles can dispatch to any sandbox provider (cloud or local). The org's key is injected into the sandbox's environment at runtime.

Cost tracking: Cost events emit to your org's billing ledger with the resolved authMode='byok'. BYOK usage is not routed through platform metering - you see raw provider consumption.

Metered

Platform supplies a managed API key. The org is entitled to use metered mode via a feature flag set by your Rensei operator. Org is billed through Rensei's cost-event ledger.

When to use:

• You want usage-based billing without managing your own keys.
• You're onboarding and don't want to hand off API keys yet.

Setup (operator):

1. Set environment variable RENSEI_METERED_KEY_<PROVIDER> on the platform (e.g. RENSEI_METERED_KEY_CLAUDE for Anthropic).
2. Optionally enable the org's feature flag metered_enabled: true in the organizations table, or set RENSEI_METERED_ALLOW_ALL=true for open access.

Setup (user): In Settings → Model Profiles, create or edit a profile and add metered to auth_modes.

Scope constraint: Org scope must have metered: { allowed: true } in its access matrix. If the org matrix denies metered and the profile's only remaining mode in the intersection would be metered, dispatch throws.

Cost attribution: A synthetic pool ID (metered_pool_{providerId}) is generated so the cost-event ledger can track spend by provider.

Rejection paths:

• Org is not entitled: the dispatcher surfaces METERED_NOT_ENTITLED with instructions to contact support.
• Key is missing: METERED_KEY_UNAVAILABLE - operators must set the RENSEI_METERED_KEY_<PROVIDER> env var.

Shared

A platform-wide free-tier key any org can use without setup. Cost is absorbed by the platform; each org has a soft daily quota.

When to use:

• You're a new user evaluating Rensei.
• You're running a limited trial.

Setup (user):

1. Add shared to a profile's auth_modes.
2. Create a dispatch.
3. If quota allows, the dispatch runs. If quota is exceeded, SHARED_QUOTA_EXCEEDED is returned.

Scope constraint: Org access matrix must allow shared. Shared is typically restricted or removed on paid plans.

Cost attribution: Uses synthetic pool ID shared_pool_{providerId}.

Rejection paths:

• Quota exceeded: user is told to upgrade or contact support.
• Key pool unavailable: contact your Rensei operator.

Host-Session

The dispatcher uses the OAuth credentials already logged in on the developer's machine (via rensei setup). Only works with local capacity pools.

When to use:

• Local development with your own credentials.
• You want to use CLI-cached OAuth tokens.

Setup (developer):

1. Run rensei setup to authenticate with your provider.
2. Add host-session to a profile's auth_modes.
3. Create a dispatch from the same machine where you ran setup.

Constraints:

• Local capacity only: The sandbox provider must be providerId='local'.
• Dispatching to cloud sandboxes (e2b, Vercel, Modal) fails with CAPACITY_INCOMPATIBLE_AUTH_MODE.

Local

Route the dispatch to a local LLM endpoint (Ollama, OpenCode) running on your network or machine.

When to use:

• Running local models (Ollama).
• On-prem LLM service.
• Full data control and no external provider dependency.

Setup:

1. Start your local endpoint (e.g. ollama serve).
2. In Settings → Capacity Pools, add a local pool and configure the endpoint URL.
3. Add local to a profile's auth_modes.
4. Create a dispatch and ensure the pool is scoped to your project.

Endpoint validation: At dispatch time, Rensei validates the endpoint is reachable. If unreachable, dispatch fails with a clear error.

Cost: No platform cost beyond sandbox capacity.

Auth mode selection guide

Use this decision tree to understand how the resolver picks a mode for a given dispatch:

Profile auth_modes × effective allowed modes (org + project scope)
  ↓ intersection
If empty → AUTHMODES_UNSATISFIABLE (fail-closed)
  ↓ not empty → pick first in preference order
byok in intersection? → byok
  → else metered in intersection? → metered
    → else shared in intersection? → shared
      → else host-session in intersection? → host-session
        → else local
  ↓ selected mode
enforceAccessPolicyGate → allowed:false? → AccessDeniedError
  ↓ allowed
proceed to credential resolution + capacity check + queue

Validation rules

When a profile is resolved for dispatch, Rensei validates the auth mode against the sandbox provider:

• byok, metered, shared: Can dispatch to any sandbox provider (cloud or local).
• host-session, local: Can ONLY dispatch to providerId='local' (daemon worker). Dispatching to e2b, Vercel, Modal, Daytona, etc. fails with AUTH_MODE_REQUIRES_LOCAL_CAPACITY.

This validation runs in validateResolvedProfile() before the work item is queued.

Cost and quota tracking

Regardless of auth mode, every successful dispatch emits a cost event stamped with the resolved scalar auth mode and provider. The pool ID identifies which mode was used:

• byok: Uses the actual pool ID configured in capacity pools.
• metered: Uses synthetic pool ID metered_pool_{providerId} (e.g. metered_pool_claude).
• shared: Uses synthetic pool ID shared_pool_{providerId} (e.g. shared_pool_gemini).
• host-session, local: Uses the local pool ID.

Dispatches that fail at the access gate (AccessDeniedError, AUTHMODES_UNSATISFIABLE) emit no cost event.

Query the observability dashboard (Settings → Observability) to see spend by auth mode.

Related pages

• Model Access Matrix - cascade-narrowing, scope-level allow/deny, blast-radius
• Model Profiles - set-based auth_modes array and credentials map
• Auth Modes (providers) - per-provider supported modes
• Credentials Overview - BYOK credential binding and cost attribution