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



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

**Clean retirement.** Retires a key without treating it as compromised. Unlike [`/kill`](/docs/api/reference/api-keys/kill), this is the planned decommission path.

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. Delete is for planned retirement; kill is for suspected compromise.

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 "Authorization: Bearer $LAYERS_API_KEY"
```

<Response status="200" description="OK - key retired">
  ```json
  {
    "apiKey": {
      "id": "c2037bb9-354d-4662-96b7-97a28ad6b6e1",
      "organizationId": "org_2481fa5c-a404-44ed-a561-565392499abc",
      "name": "legacy-nightly-cron",
      "prefix": "lp_...",
      "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.