Provider Credentials And BYOK

BYOK means “bring your own key.” It lets an organization route AI calls through provider credentials that the organization owns, while Kravos.ai still manages agents, retrieval, conversations, and usage reporting.

Use BYOK when you need provider-level ownership, separate provider billing, or direct access to a provider that is not available through the hosted OpenRouter path.

Supported Providers And Purposes

Provider credentials currently support:

• OpenAI
• Anthropic
• Google
• Mistral
• Groq
• OpenRouter

Each credential has a purpose:

BYOK must be enabled for the account. If it is not enabled, the Provider Keys UI shows a plan notice and the create endpoint returns BYOK_NOT_ALLOWED.

Add A Provider Key

1. Open Organization → Provider Keys.
2. Select the provider.
3. Select the purpose.
4. Add a human-readable label.
5. Paste the provider API key.
6. Select Save & Validate.

Kravos.ai stores the secret encrypted immediately, marks the credential PENDING, then validates it with the provider. Validation has a 10-second timeout.

Test And Update Current Behavior

The dashboard flow currently supports adding credentials and deleting credentials. It does not expose a separate re-test button or update-secret form.

Other platform surfaces can do more:

• platform credential tools can list metadata, get one credential, create a credential, update metadata, replace the stored secret, and re-test a stored credential
• the app PATCH /api/credentials/:id route updates only label, default flag, and purpose; it does not replace the secret
• the app DELETE /api/credentials/:id route soft-deactivates the credential

Replacing a secret re-validates the new value. Testing a stored credential decrypts it server-side, validates it, and returns only metadata plus validation status.

Model Selection And Fallback

Agent models use the {provider}/{model} pattern, such as anthropic/claude-sonnet-4-5. Older bare model IDs are treated as OpenAI model IDs for compatibility.

The provider/model picker asks /api/providers which providers are usable:

• OpenRouter is available as hosted when OPENROUTER_API_KEY is configured.
• Direct providers appear when the tenant has an active, valid BYOK credential with purpose chat or all.

At runtime, model resolution works in this order:

1. If BYOK is enabled and a valid active tenant credential exists for the selected provider, Kravos.ai calls that provider directly and records the turn as BYOK.
2. If no tenant credential is available, Kravos.ai uses the hosted OpenRouter gateway when OPENROUTER_API_KEY is configured and records the turn as hosted.
3. If neither path is configured, the turn fails with a provider-not-configured error.

Redaction And Secret Storage

• raw provider keys are never returned by credential list, get, create, update, or test responses
• app routes avoid selecting encryptedSecret
• platform metadata responses redact stored validation errors
• dashboard responses may show provider validation errors so admins can fix bad keys
• secrets are encrypted with aes-256-gcm using CREDENTIAL_ENCRYPTION_KEY

The encryption key must be a 32-byte hex string. If it is missing or invalid, secret encryption and decryption fail.

Rotation

For dashboard-only rotation:

1. Add the replacement key.
2. Wait for it to validate.
3. Test a small agent turn with a model from that provider.
4. Delete the old credential.

For platform-tool rotation, update the existing credential with a replacement secret. That path re-validates the new secret and keeps the credential ID stable.

For chat routing, Kravos.ai chooses an active, valid credential for the provider and purpose. Do not leave old valid credentials active if the provider account should no longer be used.

Audit Coverage

Current audit coverage is uneven:

• platform destructive credential deactivation writes a credential.delete audit event
• admin-side credential revalidation writes a credential.revalidate audit event
• the dashboard add and delete credential routes do not currently expose a user-facing credential audit trail

Secrets are not written to audit payloads.

Troubleshooting

Provider does not appear in the model picker

• confirm BYOK is enabled for the account
• confirm the credential is VALID
• confirm the credential purpose is chat or all
• for hosted-only use, confirm OPENROUTER_API_KEY is configured

Validation stays pending

The provider did not respond before the 10-second timeout. Re-test through a platform credential tool, or add a replacement key if the provider key might be wrong.

A turn used hosted credits instead of BYOK

Kravos.ai did not find a valid active BYOK credential for that provider at model-resolution time. Check provider, purpose, validation status, and whether BYOK is enabled for the account.

Related Docs

Usage & Costs

Separate hosted-credit usage from BYOK activity by provider and model.

Billing

Review plan features, hosted credit balance, and BYOK evaluation status.

Agent Settings

Choose the provider model that an agent should use.