# Revoke a Passkey

One of your passkeys, revoked for good: it confirms nothing from now on.

## Overview

- The body is optional: `reason` (1 to 500 characters, kept with it) and `stepUpToken` — a `passkey.revoke` step-up on this passkey (`passkeyId`), by any of your active passkeys, this one included. Required where your tenant's step-up mode is `enforce`; in `log` the right one is used, and a missing or wrong one refuses nothing.
- `200` with the passkey, `status` `revoked`. A step-up token it made and not yet used is refused from then on. Written to your tenant's audit trail as `passkey.revoked` [Coming soon, upon request](https://docs.aureahub.com/docs/feature-availability.md).
- `404` `PASSKEY_NOT_FOUND` for a passkey that is not yours; `409` `PASSKEY_REVOKED` when it is revoked already; then, where the step-up is enforced, `403` `STEP_UP_REQUIRED` or `STEP_UP_INVALID`. 20 requests per minute per client IP.

## Endpoint

### `POST /v1/auth/passkeys/{passkeyId}/revoke`

Authentication: bearer token required.

Revokes one of the caller's passkeys, for good.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `passkeyId` | string (uuid) | yes | The passkey's id |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | no | 1–500 characters, not only spaces |
| `stepUpToken` | string | no | A `passkey.revoke` step-up token for this passkey; 1–200 characters |

**Responses**

`200` Revoked

```json
{
  "id": "4d7b2e90-8c1f-4a63-b5d2-9e0f6a3c1b47",
  "name": "Old phone",
  "status": "revoked",
  "deviceType": "multiDevice",
  "backedUp": true,
  "transports": ["hybrid", "internal"],
  "createdAt": "2026-10-02T07:40:02.004Z",
  "lastUsedAt": "2026-10-12T11:03:27.640Z",
  "revokedAt": "2026-10-14T09:20:13.118Z",
  "revokeReason": "Replaced by a new phone"
}
```

`404` Not yours

```json
{
  "statusCode": 404,
  "error": "NotFoundError",
  "message": "No such passkey of yours",
  "details": { "code": "PASSKEY_NOT_FOUND" }
}
```

`409` Revoked already

```json
{
  "statusCode": 409,
  "error": "ConflictError",
  "message": "This passkey is revoked already",
  "details": { "code": "PASSKEY_REVOKED" }
}
```

`403` Token not for this

```json
{
  "statusCode": 403,
  "error": "ForbiddenError",
  "message": "This step-up token is not valid for this action: it is unknown, expired, used, or for something else",
  "details": {
    "code": "STEP_UP_INVALID",
    "action": "passkey.revoke",
    "tenantId": "6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0"
  }
}
```

**Example request**

```bash
curl -X POST https://api.aureahub.com/v1/auth/passkeys/$PASSKEY_ID/revoke \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Replaced by a new phone", "stepUpToken": "<stepUpToken>" }'
```

---

Web version: https://docs.aureahub.com/#passkey-revoke