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
id (path) string yes Key ID from GET /v1/ai/credentials

Request fields (body)

Field Type Required Description
name string no New key name
isDefault boolean no Make the key the default for the provider
credentials.apiKey string no New provider key
credentials.baseUrl string no New 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
success boolean Always true on success
data.id string Key ID
data.providerId string Provider ID
data.provider.slug string Provider system name
data.provider.name string Provider name
data.name string Current key name
data.isDefault boolean Default-key flag
data.lastError string | null Reset to null on a successful key update
data.lastErrorAt string | null Reset to null on a successful key update
data.createdAt string Creation time in ISO 8601
data.updatedAt string Last 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
400 invalid_request The body schema is violated
400 no_key credentials has no apiKey field
400 base_url_not_supported credentials.baseUrl was sent for a provider that has no endpoint of its own. Only custom-openai-compat accepts the field
400 base_url_required For a custom-openai-compat key, baseUrl is missing from credentials or is empty
400 base_url_invalid The new baseUrl uses a scheme other than http/https, or is malformed
400 base_url_private The new baseUrl points at a private network, or its host name does not resolve to an IP address
400 base_url_redirect An OpenAI-compatible provider responded to the key check with an HTTP redirect. For custom-openai-compat, set baseUrl to the final API address
404 not_found A key with this id was not found or does not belong to you
404 provider_not_found The key's provider was deleted
422 credential_invalid The new key failed verification with the provider
422 provider_geoblocked The 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
403 scope_missing The 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