Your own keys (BYOK)

Connecting your own provider keys (Bring Your Own Key). All requests through your key go directly to the provider and are not charged against your Vibecode balance — you pay the provider at its own rates.

Supported providers: OpenAI, Anthropic, OpenRouter, Google Gemini, Mistral AI, Groq, Together AI, DeepSeek, Fireworks AI, Cerebras, Cohere, Minimax, Qwen, Yi, plus Custom OpenAI-Compatible for connecting any API-compatible service (requires a baseUrl).

Scope: vibe:ai

What to know before you start

1. One key per provider. Connecting the same provider again via POST /v1/ai/credentials returns 409 already_exists. To replace a key, update the existing one via PATCH.
2. Verification on save. On creation and on updates to the credentials field, the key is verified with the provider (POST to /chat/completions or GET /v1/models). An invalid key returns 422 credential_invalid with the provider's error message.
3. Custom OpenAI-Compatible. Requires a baseUrl in the https://... or http://... format. Private networks (loopback, RFC 1918, link-local) are blocked as SSRF (Server-Side Request Forgery) protection.
4. The model table depends on the provider. For most providers the catalog is fixed. For a Custom service the catalog is either fetched from the provider's endpoint via fetch-models or assembled manually via models-add.
5. Key priority. Your USER key takes priority over a key that the Bitrix24 account administrator connected for everyone. If both are configured, yours is used.
6. V1 manages only USER keys. Bitrix24 account-level keys (PORTAL scope, available to all members) are connected by a Bitrix24 account administrator in the Vibecode dashboard, not through V1.

Limits

Limits are counted per Bitrix24 account: all API keys of one account share a single bucket. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). When a limit is exceeded, the API returns 429 with a Retry-After header.

A key fails to connect due to a geo-block {#geo-block-faq}

OpenAI, Anthropic, and some other providers block requests by server IP. If you see a PROVIDER_GEOBLOCKED error when saving a key, pick one of two paths:

1. Use OpenRouter — it has a POP in Singapore with no blocks. Get your own key at openrouter.ai and connect it as the BYOK provider "openrouter". Through it you can run models from OpenAI, Anthropic, Google, Meta, and dozens of others.

2. Specify your own proxy — if you already have an HTTP/HTTPS proxy in an unblocked jurisdiction, expand "Advanced settings" in the key connection form and provide a URL in the https://user:pass@host:port format. All requests through this key will go through your proxy (including the initial key check).

How the platform detects a geo-block

Signals that trigger "the provider blocks by region":

• HTTP 403 + a response body containing country / region / territory / unsupported location
• HTTP 451 (Unavailable For Legal Reasons)
• The structured OpenAI error code unsupported_country_region_territory
• A network drop on api.openai.com / api.anthropic.com (ECONNREFUSED / EHOSTUNREACH / ETIMEDOUT)

If the key passed the initial check but later started failing on real /v1/chat/completions calls, a "Geo-blocked" badge appears on the key's card in /ai. This means the provider started blocking requests after the key was saved — the fix is the same: add a proxy or migrate to OpenRouter.

⚠️ Legal note. Using a proxy to bypass geographic restrictions may violate the provider's Terms of Service. You are responsible for complying with the key's usage terms.

Provider list

GET /v1/ai/providers

Returns the catalog of providers available for connecting a BYOK key. Use it before POST /v1/ai/credentials to get the correct providerId and learn which fields the provider expects in credentials.

Parameters

No request parameters.

Examples

curl — personal key

curl https://vibecode.bitrix24.com/v1/ai/providers \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl https://vibecode.bitrix24.com/v1/ai/providers \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/ai/providers', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
data.forEach((p) => {
  const fields = Object.keys(p.credentialFields).join(', ')
  console.log(`${p.name} (${p.slug}) — required fields: ${fields}`)
})

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/ai/providers', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
const openai = data.find((p) => p.slug === 'openai')
console.log('OpenAI ID:', openai.id)

Response fields

Response example

{
  "success": true,
  "data": [
    {
      "id": "anthropic",
      "name": "Anthropic",
      "slug": "anthropic",
      "credentialFields": {
        "apiKey": {
          "type": "password",
          "label": "API Key",
          "required": true
        }
      }
    },
    {
      "id": "cprv_custom_seed",
      "name": "Custom OpenAI-Compatible",
      "slug": "custom-openai-compat",
      "credentialFields": {
        "apiKey": {
          "type": "password",
          "label": "API Key",
          "required": true
        },
        "baseUrl": {
          "type": "url",
          "label": "Base URL",
          "required": true,
          "placeholder": "https://api.example.com/v1",
          "help": "OpenAI-compatible endpoint."
        }
      }
    },
    {
      "id": "openai",
      "name": "OpenAI",
      "slug": "openai",
      "credentialFields": {
        "apiKey": {
          "type": "password",
          "label": "API Key",
          "required": true
        }
      }
    }
  ]
}

Error response example

403 scope_missing — the API key does not have the vibe:ai scope:

{
  "success": false,
  "error": {
    "code": "scope_missing",
    "message": "API key does not have the vibe:ai scope"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

The bitrix provider is excluded. The list does not contain the platform provider bitrix — its models (BitrixGPT 5.5, GPT-OSS, Whisper, etc.) are available to everyone without connecting a BYOK key.

Most providers require only apiKey. The baseUrl field is required only for custom-openai-compat. For all other providers baseUrl is fixed by the platform and is not passed in credentials.

The system name custom-openai-compat is for arbitrary services. Use it to connect any OpenAI-compatible service: Minimax, Cerebras, Cohere, a corporate vLLM/Ollama, a local inference server. After connecting, models are either loaded automatically via fetch-models or registered manually via models-add.

The hint field. For some providers the hint field contains the domain of the key-issuing page: platform.deepseek.com, console.groq.com, aistudio.google.com. Show it to the user next to the key input field.

See also

• Connect a provider key
• Your own keys (BYOK)
• AI Router