For AI agents: markdown of this page — /docs-content-en/ai/credentials/update.md documentation index — /llms.txt

Update a provider key

PATCH /v1/ai/credentials/:id

Updates the name, the isDefault flag, and/or the key itself. If the request includes the credentials field, the new key is re-verified with the provider before it is saved. A key that fails the check is not saved and nothing changes in the database. The name and isDefault fields are updated without verification.

Parameters

Parameter Type Required Description
Parameterid (path) Typestring Requiredyes DescriptionKey ID from GET /v1/ai/credentials

Request fields (body)

Field Type Required Description
Fieldname Typestring Requiredno DescriptionNew key name
FieldisDefault Typeboolean Requiredno DescriptionMake the key the default for the provider
Fieldcredentials.apiKey Typestring Requiredno DescriptionNew provider key
Fieldcredentials.baseUrl Typestring Requiredno DescriptionNew provider API address. Accepted only for custom-openai-compat, where it is required whenever the credentials field is passed; refused for every other provider

Examples

curl — personal key

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/ai/credentials/cred_abc123def456 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI (new name)",
    "credentials": {
      "apiKey": "YOUR_NEW_API_KEY"
    }
  }'

curl — OAuth application

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/ai/credentials/cred_abc123def456 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI (new name)",
    "credentials": {
      "apiKey": "YOUR_NEW_API_KEY"
    }
  }'

JavaScript — personal key

javascript 
const id = 'cred_abc123def456'
const res = await fetch(`https://vibecode.bitrix24.com/v1/ai/credentials/${id}`, {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'OpenAI (new name)',
    credentials: { apiKey: 'YOUR_NEW_API_KEY' },
  }),
})

const { success, data } = await res.json()
if (success) console.log('Key updated at', data.updatedAt)

JavaScript — OAuth application

javascript 
const id = 'cred_abc123def456'
const res = await fetch(`https://vibecode.bitrix24.com/v1/ai/credentials/${id}`, {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'OpenAI (new name)',
    credentials: { apiKey: 'YOUR_NEW_API_KEY' },
  }),
})

const { success, data } = await res.json()
if (success) console.log('Key updated at', data.updatedAt)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typestring DescriptionKey ID
Fielddata.providerId Typestring DescriptionProvider ID
Fielddata.provider.slug Typestring DescriptionProvider system name
Fielddata.provider.name Typestring DescriptionProvider name
Fielddata.name Typestring DescriptionCurrent key name
Fielddata.isDefault Typeboolean DescriptionDefault-key flag
Fielddata.lastError Typestring | null DescriptionReset to null on a successful key update
Fielddata.lastErrorAt Typestring | null DescriptionReset to null on a successful key update
Fielddata.createdAt Typestring DescriptionCreation time in ISO 8601
Fielddata.updatedAt Typestring DescriptionLast update time in ISO 8601

Response example

JSON 
{
  "success": true,
  "data": {
    "id": "cred_abc123def456",
    "providerId": "openai",
    "provider": {
      "slug": "openai",
      "name": "OpenAI"
    },
    "name": "OpenAI (new name)",
    "isDefault": true,
    "lastError": null,
    "lastErrorAt": null,
    "createdAt": "2026-04-15T10:00:00.000Z",
    "updatedAt": "2026-04-27T11:35:00.000Z"
  }
}

Error response example

422 credential_invalid — the new key failed verification with the provider:

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

Errors

HTTP Code Description
HTTP400 Codeinvalid_request DescriptionThe body schema is violated
HTTP400 Codeno_key Descriptioncredentials has no apiKey field
HTTP400 Codebase_url_not_supported Descriptioncredentials.baseUrl was sent for a provider that has no endpoint of its own. Only custom-openai-compat accepts the field
HTTP400 Codebase_url_required DescriptionFor a custom-openai-compat key, baseUrl is missing from credentials or is empty
HTTP400 Codebase_url_invalid DescriptionThe new baseUrl uses a scheme other than http/https, or is malformed
HTTP400 Codebase_url_private DescriptionThe new baseUrl points at a private network, or its host name does not resolve to an IP address
HTTP400 Codebase_url_redirect DescriptionAn OpenAI-compatible provider responded to the key check with an HTTP redirect. For custom-openai-compat, set baseUrl to the final API address
HTTP404 Codenot_found DescriptionA key with this id was not found or does not belong to you
HTTP404 Codeprovider_not_found DescriptionThe key's provider was deleted
HTTP422 Codecredential_invalid DescriptionThe new key failed verification with the provider
HTTP422 Codeprovider_geoblocked DescriptionThe provider rejected the key check based on our server's region. Connect your own proxy or switch to OpenRouter. The response carries a suggestions field
HTTP403 Codescope_missing DescriptionThe API key lacks the vibe:ai scope

Full list of common API errors — Errors.

Known specifics

Verification only when credentials changes. If the request has no credentials field (only name or isDefault are updated), the provider is not called and the lastError/lastErrorAt fields are not reset.

An empty request body is allowed. A PATCH with an empty body {} leaves the name, the flag, and the key unchanged and returns the key. It is not a way to check a key: the call is still an update and counts against the key-update rate limit. To read a key without changing anything, use GET /v1/ai/credentials.

Access to your own keys only. The endpoint works only with the current user's USER keys. Updating another user's key or a PORTAL key returns 404.

See also