## 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 |
|----------|-----|:-----:|---------|
| `id` (path) | string | yes | Application card ID. This is not the ID of an OAuth application or a server. List: [`GET /v1/applications`](/docs/applications/list) |
| `name` (path) | string | yes | Secret name. List: [`GET /v1/applications/:id/secrets`](/docs/applications/app-secrets/list) |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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 |
|------|-----|---------|
| `success` | boolean | `true` on success |
| `data.secret` | null | Always `null`: the name no longer exists |
| `data.state` | object | State of applying the new set |
| `data.state.desiredRevision` | number | Number of the current set. Deletion increases it by one |
| `data.state.appliedRevision` | number | Number of the set the application has confirmed receiving. Catches up with `desiredRevision` once the platform confirms the restart |
| `data.state.appliedServerId` | string \| null | ID of the server where the set is applied. Matches `server.id` in [`GET /v1/applications/:id`](/docs/applications/get) |
| `data.state.status` | string | `PENDING` right after deletion. The other values are described under `state.status` on the [List application secrets](/docs/applications/app-secrets/list) page |
| `data.state.failureCode` | string \| null | Failure reason when `FAILED`. The codes are in the "Failure and retry" section of [Application secrets](/docs/applications/app-secrets) |
| `data.state.deliveredNames` | array | Names the platform has already passed to the application, including deleted ones |
| `data.state.serviceName` | string \| null | The application's service on a standalone machine, recorded by the platform on deploy. `null` in Galaxy and before such a deploy |
| `data.state.updatedAt` | string | Time 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 |
|------|-----|---------|
| 404 | `SECRET_NOT_FOUND` | The application has no such name, including on a repeated deletion |
| 404 | `APPLICATION_NOT_FOUND` | The 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 |
| 400 | `SECRET_INVALID_NAME` | Invalid or reserved name, other than a system secret name |
| 409 | `SECRET_SYSTEM` | A 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 |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | Key not found |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | A read-only key cannot delete names |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | A Cowork subscription key with the `vibe:cowork` scope cannot delete names |
| 403 | `EXTERNAL_COLLABORATOR_KEY_SERVER_MISMATCH` | The external development member's key is not linked to a machine, and the application has no machine either |
| 403 | `EXTERNAL_COLLABORATOR_NOT_A_MEMBER` | Key of an external development member whose membership on the machine was revoked or has expired |
| 403 | `PORTAL_COLLABORATOR_NOT_A_MEMBER` | Key of a development team member who is no longer in the machine's team or is not linked to it |
| 429 | `RATE_LIMIT_EXCEEDED` | The 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 |
| 500 | `SECRET_OPERATION_FAILED` | The operation failed. The response does not include the original error |

Full list of common API errors — [Errors](/docs/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](/docs/applications/app-secrets).

## See also

- [Application secrets](/docs/applications/app-secrets)
- [List application secrets](/docs/applications/app-secrets/list)
- [Create a secret name](/docs/applications/app-secrets/create)
- [Application catalog](/docs/applications)