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.
Management flow
- Create a personal or team credential with a provider descriptor.
- For a team credential, optionally create an external HTTPS target and a channel definition.
- Preview the deployment. Preview writes a deterministic, secret-free receipt and makes no network request.
- Apply the exact preview. A changed channel fails closed and requires a new preview.
- 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
| Method | Path | Purpose |
|---|---|---|
GET | /api/v1/byok/providers | List provider descriptor templates. |
GET, POST | /api/v1/byok/personal/sources | List or create personal management-only credentials. |
GET, POST | /api/v1/team/byok/sources | List or create team management-only credentials. |
GET, POST | /api/v1/team/byok/targets | List or create team-owned external targets. |
GET, POST | /api/v1/team/byok/channels | List or create management channel definitions. |
POST | /api/v1/team/byok/deployments/preview | Create a secret-free deployment preview. |
POST | /api/v1/team/byok/deployments/{deployment_id}/apply | Apply one exact preview. |
POST | /api/v1/team/byok/deployments/{deployment_id}/reconcile | Discover the result of an uncertain apply without resending the provider credential. |
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
| Status | Meaning |
|---|---|
previewed | Local, secret-free plan exists; no remote request was made. |
applying | One apply owns the operation. |
deployed | The external channel was uniquely identified and recorded. |
failed | The external system definitely rejected the request; a new preview may retry. |
reconciliation_required | The remote outcome is uncertain; discovery-only reconciliation is required. |
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.