#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 — 422 credential_invalid with a message from the provider.
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. Portal-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 portal: all API keys of one portal share a single bucket. On exceeding a limit you get 429 with a Retry-After header.

#A key doesn't work from our region {#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 — they have 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 broke 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 actions are 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. Responsibility for complying with the key's usage terms rests with you.

#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 key
• Your own keys (BYOK)
• AI Router