Для AI-агентов: markdown этой страницы — /docs-content/ai/credentials/create.md индекс документации — /llms.txt

Подключить ключ провайдера

POST /v1/ai/credentials

Подключает новый ключ провайдера к вашему пользователю (USER scope). Ключ автоматически проверяется у провайдера до сохранения: непрошедший проверку ключ не сохраняется. Один пользователь может подключить только один ключ на каждого провайдера.

Поля запроса (body)

Поле Тип Обяз. По умолч. Описание
ПолеproviderId Типstring Обяз.да По умолч.— ОписаниеID провайдера. Список: GET /v1/ai/providers
Полеname Типstring Обяз.да По умолч.— ОписаниеПроизвольное имя ключа для отображения в списке
Полеcredentials.apiKey Типstring Обяз.да По умолч.— ОписаниеКлюч от провайдера (например, sk-... для OpenAI)
Полеcredentials.baseUrl Типstring Обяз.условно По умолч.— ОписаниеОбязательно для custom-openai-compat и запрещено для остальных провайдеров. Формат: https://api.example.com/v1. Только http/https, приватные сети запрещены
ПолеisDefault Типboolean Обяз.нет По умолч.false ОписаниеИспользовать этот ключ по умолчанию для провайдера

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/ai/credentials \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "openai",
    "name": "Мой личный OpenAI",
    "credentials": {
      "apiKey": "sk-proj-..."
    },
    "isDefault": true
  }'

curl — OAuth-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/ai/credentials \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "openai",
    "name": "Мой личный OpenAI",
    "credentials": {
      "apiKey": "sk-proj-..."
    },
    "isDefault": true
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/ai/credentials', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    providerId: 'openai',
    name: 'Мой личный OpenAI',
    credentials: { apiKey: 'sk-proj-...' },
    isDefault: true,
  }),
})

const { success, data } = await res.json()
if (success) console.log('Ключ подключён, ID:', data.id)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/ai/credentials', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    providerId: 'openai',
    name: 'Мой личный OpenAI',
    credentials: { apiKey: 'sk-proj-...' },
    isDefault: true,
  }),
})

const { data } = await res.json()
console.log('ID:', data.id)

Подключение Custom OpenAI-Compatible сервиса

Для произвольного OpenAI-совместимого сервиса (Minimax, Cerebras, Cohere, корпоративный vLLM/Ollama и т. п.) используйте providerId: cprv_custom_seed и обязательно укажите baseUrl:

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/ai/credentials \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "cprv_custom_seed",
    "name": "Корпоративный сервис",
    "credentials": {
      "apiKey": "sk-corp-...",
      "baseUrl": "https://llm.example.com/v1"
    }
  }'

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata.id Типstring ОписаниеУникальный ID созданного ключа
Полеdata.providerId Типstring ОписаниеID провайдера
Полеdata.provider.slug Типstring ОписаниеСистемное имя провайдера
Полеdata.provider.name Типstring ОписаниеНазвание провайдера
Полеdata.name Типstring ОписаниеИмя ключа из запроса
Полеdata.isDefault Типboolean ОписаниеФлаг ключа по умолчанию
Полеdata.createdAt Типstring ОписаниеВремя создания в ISO 8601
Полеdata.updatedAt Типstring ОписаниеВремя последнего обновления в ISO 8601

Пример ответа

HTTP-статус 201 Created:

JSON 
{
  "success": true,
  "data": {
    "id": "cred_abc123def456",
    "providerId": "openai",
    "provider": {
      "slug": "openai",
      "name": "OpenAI"
    },
    "name": "Мой личный OpenAI",
    "isDefault": true,
    "createdAt": "2026-04-27T11:30:00.000Z",
    "updatedAt": "2026-04-27T11:30:00.000Z"
  }
}

Пример ответа при ошибке

422 credential_invalid — ключ не прошёл верификацию у провайдера:

JSON 
{
  "success": false,
  "error": {
    "code": "credential_invalid",
    "message": "OpenAI API 401: Incorrect API key provided"
  }
}

Ошибки

HTTP Код Описание
HTTP400 Кодinvalid_request ОписаниеНарушена схема body (нет обязательных полей)
HTTP400 Кодno_key ОписаниеВ credentials нет поля apiKey
HTTP400 Кодbase_url_not_supported Описаниеcredentials.baseUrl передан ключу провайдера, у которого нет своего адреса эндпоинта. Поле принимает только custom-openai-compat
HTTP400 Кодbase_url_invalid ОписаниеbaseUrl использует не http/https или некорректен
HTTP400 Кодbase_url_private ОписаниеbaseUrl указывает на приватную сеть или не разрешается в IP-адрес через DNS
HTTP404 Кодprovider_not_found ОписаниеПровайдер с таким providerId не существует или отключён
HTTP409 Кодalready_exists ОписаниеКлюч для этого провайдера уже подключён — используйте PATCH /v1/ai/credentials/:id
HTTP422 Кодcredential_invalid ОписаниеКлюч не прошёл верификацию у провайдера. Сообщение содержит детали от провайдера
HTTP422 Кодprovider_geoblocked ОписаниеПровайдер отклонил проверку ключа по региону нашего сервера. Подключите свой прокси или перейдите на OpenRouter. Ответ несёт поле suggestions
HTTP403 Кодscope_missing ОписаниеAPI-ключу не хватает скоупа vibe:ai

Полный список общих ошибок API — Ошибки.

Лимит создания ключей: 10 запросов в минуту (единая корзина на портал — все ключи портала делят её). Действующее значение — в заголовке x-ratelimit-limit.

Известные особенности

Верификация перед сохранением. Ключ проверяется у провайдера через verify() — это HTTP-запрос к GET /v1/models или (если провайдер не поддерживает models) к POST /v1/chat/completions с минимальным телом. Тайм-аут проверки — 10 секунд. При некорректном ключе ничего не сохраняется в базе.

SSRF-защита для Custom-провайдера. baseUrl для custom-openai-compat обязательно проходит проверку: запрещены приватные сети (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16), IPv6 link-local и ULA, IPv4-mapped IPv6. Принимаются только http:///https:// схемы.

Сообщение об ошибке очищено. Текст ошибки от провайдера обрезается до 200 символов, URL заменяются на плейсхолдер [URL] — это защищает от случайной утечки внутренних адресов в логах клиента.

Смотрите также