Skip to main content

LLM Provider Keys API

The LLM Provider Keys API manages the BYOK provider keys used by Quave ONE agent conversations and automations.

Security and validation​

  • User-scoped provider keys belong only to the authenticated user.
  • Account-scoped provider keys require the Manage Credentials role for list, get, create, update, delete, set-default, and test. Revealing an account key additionally requires Secrets Access.
  • Metadata responses never include plaintext API keys.
  • Create and update use the same backend validation as the dashboard UI, including provider support, required base URL checks, duplicate-name checks, immutable provider on update, encryption type checks, and default-key normalization.
  • Revealing a key emits a secret-decrypt audit event and requires quave:read:secrets for MCP callers.

List provider keys​

User-scoped keys:

curl -H 'Authorization: YOUR_TOKEN' \
  'https://api.quave.cloud/api/public/v1/agent/llm-provider-keys?scope=user'

Account-scoped keys:

curl -H 'Authorization: YOUR_TOKEN' \
  'https://api.quave.cloud/api/public/v1/agent/llm-provider-keys?accountId=ACC_ID&scope=account'

Create a provider key​

Omit accountId to create a user-scoped key. Include accountId to create an account-scoped key.

curl -X POST \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "ACC_ID",
    "name": "OpenAI production",
    "provider": "openai",
    "apiKey": "PROVIDER_API_KEY",
    "defaultModel": "gpt-5",
    "isDefault": true,
    "enabled": true
  }' \
  https://api.quave.cloud/api/public/v1/agent/llm-provider-key

OpenRouter is a first-class provider. Its standard API URL is applied automatically:

curl -X POST \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "ACC_ID",
    "name": "OpenRouter production",
    "provider": "openrouter",
    "apiKey": "PROVIDER_API_KEY",
    "defaultModel": "~deepseek/deepseek-v4-flash-latest",
    "enabled": true
  }' \
  https://api.quave.cloud/api/public/v1/agent/llm-provider-key

You can still configure OpenRouter as openai-compatible with an OpenRouter base URL. Both representations use the same OpenRouter policy: account attribution, zero-data-retention routing, provider retry behavior, and reachability checks.

Get or update a provider key​

curl -H 'Authorization: YOUR_TOKEN' \
  'https://api.quave.cloud/api/public/v1/agent/llm-provider-key?providerKeyId=PROVIDER_KEY_ID'
curl -X PATCH \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "providerKeyId": "PROVIDER_KEY_ID",
    "defaultModel": "gpt-5-mini",
    "enabled": true
  }' \
  https://api.quave.cloud/api/public/v1/agent/llm-provider-key

Set default, test, reveal, or delete​

curl -X POST \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "providerKeyId": "PROVIDER_KEY_ID", "accountId": "ACC_ID" }' \
  https://api.quave.cloud/api/public/v1/agent/llm-provider-key/default
curl -X POST \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "providerKeyId": "PROVIDER_KEY_ID", "accountId": "ACC_ID" }' \
  https://api.quave.cloud/api/public/v1/agent/llm-provider-key/test
curl -X POST \
  -H 'Authorization: YOUR_TOKEN' \
  'https://api.quave.cloud/api/public/v1/agent/llm-provider-key/reveal?providerKeyId=PROVIDER_KEY_ID&accountId=ACC_ID'
curl -X DELETE \
  -H 'Authorization: YOUR_TOKEN' \
  'https://api.quave.cloud/api/public/v1/agent/llm-provider-key?providerKeyId=PROVIDER_KEY_ID&accountId=ACC_ID'

Managing credentials versus revealing secrets​

Managing a credential does not grant permission to read the secrets stored inside it. Revealing an existing account credential secret or account LLM provider key requires both Manage Credentials and Secrets Access. Secrets Access alone does not grant credential management. A manager without Secrets Access can retain existing masked/encrypted values while editing metadata or replacing a value, but cannot reveal the stored value. Personal keys remain owner-scoped.

Selecting a credential for a workload, testing its connection server-side, or using it during deploy/build does not reveal its plaintext to the caller. Those operations retain their existing permissions. See User Roles for the migration and complete role matrix.