# DELETE /v1/api-keys/:keyId (/docs/api/reference/api-keys/delete)



<Endpoint method="DELETE" path="/v1/api-keys/{keyId}" auth="X-Api-Key" phase="1" />

**Clean retirement.** Flips `is_active=false` and stamps `revoked_at`. Unlike [`/kill`](/docs/api/reference/api-keys/kill), this does NOT set `kill_switch` — the key is cleanly retired, not quarantined as compromised. Returned errors on the deleted key are `503 KILL_SWITCH` all the same (auth refuses inactive keys), but the audit trail records `api_key.deleted`, not `api_key.killed`, which matters for incident forensics.

Use this when:

* A service that owned the key has been decommissioned.
* You're consolidating keys down to a smaller set.
* An employee with key access has left and you want to retire *their* key (not quarantine the whole namespace).

Do NOT use this when the secret may have leaked — call [`/kill`](/docs/api/reference/api-keys/kill) instead. `/kill` trips the kill-switch, which is observable both to your audit trail and to internal Layers monitoring; a plain delete looks operational, a kill looks like an incident.

A deleted key cannot be revived via the partner surface. Partner key issuance is dashboard / admin-only — there is no partner-API endpoint to mint a new key. Issue a fresh key from the Layers dashboard, then deploy it.

<Parameters
  title="Path"
  rows="[
  { name: 'keyId', type: 'string (UUID)', required: true, description: 'The api_keys.id of the key to delete. Must belong to the same org as the calling key.' },
]"
/>

## Example [#example]

```bash
# Retire the key for a decommissioned service
curl -X DELETE https://api.layers.com/v1/api-keys/c2037bb9-354d-4662-96b7-97a28ad6b6e1 \
  -H "X-Api-Key: $LAYERS_API_KEY"
```

<Response status="200" description="OK — key retired">
  ```json
  {
    "apiKey": {
      "id": "c2037bb9-354d-4662-96b7-97a28ad6b6e1",
      "organizationId": "2481fa5c-a404-44ed-a561-565392499abc",
      "name": "legacy-nightly-cron",
      "prefix": "lp_live_01HXA1NHKJZXPV8RAB",
      "killSwitch": false,
      "isActive": false,
      "revokedAt": "2026-04-20T18:14:02.187Z"
    },
    "deleted": true
  }
  ```
</Response>

## Errors [#errors]

| Status | Code         | When                                                 |
| ------ | ------------ | ---------------------------------------------------- |
| 404    | `NOT_FOUND`  | Key ID doesn't exist, or belongs to a different org. |
| 422    | `VALIDATION` | Missing `:keyId`.                                    |

## See also [#see-also]

* [Kill](/docs/api/reference/api-keys/kill) — emergency stop; sets kill-switch, records as incident.
* [Rotate](/docs/api/reference/api-keys/rotate) — replace the secret without retiring the key.
* [API keys concept](/docs/api/concepts/api-keys) — lifecycle diagram.
* [Audit log](/docs/api/reference/audit-log/list) — `api_key.deleted` events.