Test a provider key

POST /v1/ai/credentials/:id/test

Re-verifies a saved key with the provider. It changes nothing in the credentials themselves, but updates the key's lastError and lastErrorAt fields depending on the result. Use it when you suspect the key has expired or the provider changed its API.

Parameters

Examples

curl — personal key

curl -X POST https://vibecode.bitrix24.com/v1/ai/credentials/cred_abc123def456/test \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

JavaScript — personal key

const id = 'cred_abc123def456'
const res = await fetch(`https://vibecode.bitrix24.com/v1/ai/credentials/${id}/test`, {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log(data.valid ? 'Key is valid' : `Error: ${data.error}`)

JavaScript — OAuth application

const id = 'cred_abc123def456'
const res = await fetch(`https://vibecode.bitrix24.com/v1/ai/credentials/${id}/test`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
if (!data.valid) alert(`Key is invalid: ${data.error}`)

Response fields

Response example

Key is valid:

{
  "success": true,
  "data": {
    "valid": true
  }
}

Key was rejected by the provider:

{
  "success": true,
  "data": {
    "valid": false,
    "error": "OpenAI API 401: Incorrect API key provided"
  }
}

Error response example

404 not_found — the key was not found or belongs to another user:

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Credential not found"
  }
}

Errors

Full list of common API errors — Errors.

Test limit: 10 requests per minute (one bucket per Bitrix24 account). The effective value is returned in the x-ratelimit-limit header.

Known specifics

An invalid key is not an endpoint error. If the provider rejects the key, the endpoint returns 200 OK with success: true and data.valid: false. HTTP errors (4xx/5xx) are returned only for problems with the request itself (no key, no access, nothing to decrypt). The only exception is a regional block: the provider rejected the check based on our server's region, and the endpoint responds with 422 provider_geoblocked.

Writing the result to lastError. The endpoint updates the key's lastError and lastErrorAt fields in the database. On success it resets them; on failure it records the provider's error text. These fields are visible in GET /v1/ai/credentials.

Verification timeout — 10 seconds. If the provider does not respond within 10 seconds, the endpoint returns valid: false with a timeout message.

The Custom provider is verified against the key's baseUrl. For custom-openai-compat, the key is verified against the baseUrl saved in the credentials. If the provider has no GET /v1/models, the check is performed via POST /v1/chat/completions instead.

See also

• List keys
• Update a key
• Connect a provider key