For AI agents: markdown of this page — /docs-content-en/applications/app-secrets/delete.md documentation index — /llms.txt

Delete a secret

DELETE /v1/applications/:id/secrets/:name

Deletes a secret name together with its stored value. A deleted value cannot be restored: set it again on the application card.

Parameters

Parameter Type Required Description
Parameterid (path) Typestring Requiredyes DescriptionApplication card ID. This is not the ID of an OAuth application or a server. List: GET /v1/applications
Parametername (path) Typestring Requiredyes DescriptionSecret name. List: GET /v1/applications/:id/secrets

Examples

curl — personal key

Terminal 
curl -X DELETE https://vibecode.bitrix24.com/v1/applications/cmsw806qi0000tdskiw2aegii/secrets/PAYMENT_TOKEN \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X DELETE https://vibecode.bitrix24.com/v1/applications/cmsw806qi0000tdskiw2aegii/secrets/PAYMENT_TOKEN \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.com/v1/applications/${id}/secrets/PAYMENT_TOKEN`, {
  method: 'DELETE',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()

console.log('New set:', data.state.desiredRevision, data.state.status)

JavaScript — OAuth application

javascript 
const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.com/v1/applications/${id}/secrets/PAYMENT_TOKEN`, {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

Success — HTTP 200.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.secret Typenull DescriptionAlways null: the name no longer exists
Fielddata.state Typeobject DescriptionState of applying the new set
Fielddata.state.desiredRevision Typenumber DescriptionNumber of the current set. Deletion increases it by one
Fielddata.state.appliedRevision Typenumber DescriptionNumber of the set the application has confirmed receiving. Catches up with desiredRevision once the platform confirms the restart
Fielddata.state.appliedServerId Typestring | null DescriptionID of the server where the set is applied. Matches server.id in GET /v1/applications/:id
Fielddata.state.status Typestring DescriptionPENDING right after deletion. The other values are described under state.status on the List application secrets page
Fielddata.state.failureCode Typestring | null DescriptionFailure reason when FAILED. The codes are in the "Failure and retry" section of Application secrets
Fielddata.state.deliveredNames Typearray DescriptionNames the platform has already passed to the application, including deleted ones
Fielddata.state.serviceName Typestring | null DescriptionThe application's service on a standalone machine, recorded by the platform on deploy. null in Galaxy and before such a deploy
Fielddata.state.updatedAt Typestring DescriptionTime of the last state change, ISO 8601

Response example

JSON 
{
  "success": true,
  "data": {
    "secret": null,
    "state": {
      "desiredRevision": 1,
      "appliedRevision": 0,
      "appliedServerId": null,
      "status": "PENDING",
      "failureCode": null,
      "deliveredNames": [],
      "serviceName": null,
      "updatedAt": "2026-10-22T12:46:24.093Z"
    }
  }
}

Error response example

404 — the application has no such name:

JSON 
{
  "success": false,
  "error": {
    "code": "SECRET_NOT_FOUND",
    "message": "SECRET_NOT_FOUND"
  }
}

Errors

HTTP Code Description
HTTP404 CodeSECRET_NOT_FOUND DescriptionThe application has no such name, including on a repeated deletion
HTTP404 CodeAPPLICATION_NOT_FOUND DescriptionThe application does not exist or there is no access to it, including an application on a different machine than the one the development member's key is linked to. Or the feature is not enabled for the portal
HTTP400 CodeSECRET_INVALID_NAME DescriptionInvalid or reserved name, other than a system secret name
HTTP409 CodeSECRET_SYSTEM DescriptionA platform system secret name — VIBE_AUTH_SECRET, VIBE_AUTH_SECRET_PREVIOUS or VIBE_AUTH_SECRET_REVOKED. A system secret cannot be deleted through the API. The answer is the same even if the application has no such secret
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionKey not found
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionA read-only key cannot delete names
HTTP403 CodeINFRA_FORBIDDEN_FOR_COWORK_KEY DescriptionA Cowork subscription key with the vibe:cowork scope cannot delete names
HTTP403 CodeEXTERNAL_COLLABORATOR_KEY_SERVER_MISMATCH DescriptionThe external development member's key is not linked to a machine, and the application has no machine either
HTTP403 CodeEXTERNAL_COLLABORATOR_NOT_A_MEMBER DescriptionKey of an external development member whose membership on the machine was revoked or has expired
HTTP403 CodePORTAL_COLLABORATOR_NOT_A_MEMBER DescriptionKey of a development team member who is no longer in the machine's team or is not linked to it
HTTP429 CodeRATE_LIMIT_EXCEEDED DescriptionThe secrets methods limit is 60 requests per minute per user within a portal, shared by the list, create and delete methods and split across replicas. A rejection by the general API request limit comes with the same code. x-ratelimit-limit reports the effective limit for the key
HTTP500 CodeSECRET_OPERATION_FAILED DescriptionThe operation failed. The response does not include the original error

Full list of common API errors — Errors.

Known specifics

Restart without a deploy. The new set is applied in the background, the same way as after a value is changed on the card: the running application restarts without the deleted value and does not respond while it restarts. A sleeping machine applies the set after it wakes up. Details are in the "Without a deploy" section of Application secrets.

See also