BYOK credential management

The BYOK vault at app.quotaflow.ai/models/byok stores personal or team-owned provider credentials as management-only assets. Stored secrets are encrypted and returned only as redacted previews.

Saving a credential, creating a management channel, or deploying that channel to an external control plane does not activate a Quotaflow route. Management-only credentials are unavailable to Quotaflow inference APIs and do not change managed capacity or fallback behavior.

Access boundaries

• Any signed-in user can manage personal credentials. They remain private to that user.
• Team owners and team administrators can manage organization credentials, targets, channels, and deployment receipts.
• Platform administrators can see a redacted inventory, but cannot read stored credentials or target administrator tokens.

Use the dashboard whenever possible. The management API uses the signed-in dashboard bearer session at https://api.quotaflow.ai/api/v1; it does not accept a customer qf_... inference key.

Fallback choice and platform fallback

When your admitted third-party supply cannot serve a request, what happens next follows one of three answers you give at onboarding (the start-plan prompt), the same answer across every product line (Gemini, GPT, Claude):

• BYOK fallback — Quotaflow falls back to your own provider credential. Traffic served on your own credential is never billed by Quotaflow.
• Platform fallback — Quotaflow serves the request from its own official capacity.
• No fallback — the request is refused when no qualified third-party supply can serve it.

How a platform-fallback request is billed depends on your terms:

• Contracted organizations are locked in. If your organization holds contracted terms for a model group, platform fallback is on for that group automatically, billed at your contracted rate, and cannot be switched off from the dashboard — the fallback follows the contract, so changing it means changing the contract through your account manager. The dashboard shows these groups as locked.
• Self-selected platform fallback bills at list price. If you chose platform fallback without contracted terms, fallback traffic is billed at the official list price (multiplier 1.00). Any discount you have applies only to the third-party supply it was negotiated for, never to the platform-fallback leg.

Management flow

1. Create a personal or team credential with a provider descriptor.
2. For a team credential, optionally create an external HTTPS target and a channel definition.
3. Preview the deployment. Preview writes a deterministic, secret-free receipt and makes no network request.
4. Apply the exact preview. A changed channel fails closed and requires a new preview.
5. If the remote result is uncertain, reconcile by discovery. Do not submit another apply while the status is reconciliation_required.

The deployed status means only that an external channel was created and recorded. It does not make the credential routable through Quotaflow APIs.

API endpoints

Team list requests use the organization_id query parameter. Team writes include organization_id in the JSON body, except team source creation, which uses the query parameter.

Create a personal management-only credential

curl https://api.quotaflow.ai/api/v1/byok/personal/sources \
  -H "Authorization: Bearer $QUOTAFLOW_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My OpenAI key",
    "credential": "'$PROVIDER_API_KEY'",
    "descriptor": {
      "provider": "openai",
      "credential_type": "api_key",
      "config": {"endpoint": "https://api.openai.com"}
    }
  }'

The response never returns the raw credential. Provider-specific fields are validated before storage. Unsupported connectors fail closed instead of creating a partially usable channel.

Deployment states

No state in this table is evidence that a Quotaflow customer key can route through the credential. Route activation requires a separate reviewed workflow and separate customer-key validation.