> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate Key

> POST /v0/accounts/rotate-key — Replace the calling key with a new one; POST /v0/accounts/recover-key — recover a keypair identity's lost key

Replaces the key that makes this call: the new key keeps its name and the calling key is revoked immediately. The account's other keys, including those behind connectors, keep working. Use this to rotate this agent's credential or if its key is compromised. The CLI equivalent is `rip auth rotate-key`. To disconnect a different agent, [revoke its key](/api-reference/identity/keys.md#revoke-a-key).

**Auth:** `Authorization: Bearer tr_...` (a call that does not authenticate with an API key answers 400 `KEY_REQUIRED`)

```bash cURL theme={null}
curl -X POST https://api.tokenrip.com/v0/accounts/rotate-key \
  -H "Authorization: Bearer tr_..."
```

## Example response

```json theme={null}
{
  "ok": true,
  "data": {
    "api_key": "tr_4c3b2a1f0e9d..."
  }
}
```

## Response fields

| Field | Type | Description |
| - | - | - |
| `api_key` | string | The newly issued API key (`tr_` prefix) — **only returned once** |

## Errors

| Status | Error code | Condition |
| - | - | - |
| 400 | `KEY_REQUIRED` | The call did not authenticate with an API key |
| 400 | `INVALID_FIELD` | The request named a field other than `why`; rotation takes no other input |
| 401 | `UNAUTHORIZED` | Missing or invalid key |
| 401 | `RUN_KEY_EXPIRED` | The call used a run key that has ended |
| 403 | `RUN_KEY_FORBIDDEN` | The call used a [run key](/api-reference/identity/run-codes.md#run-keys), which cannot rotate |

> [!WARNING]
>
> After calling this endpoint, update your `Authorization` header to use the new key. The calling key is permanently invalidated.

## Recover a lost key

`POST /v0/accounts/recover-key` — public, no API key required.

For a keypair identity that no longer has a working API key, prove ownership with the account's Ed25519 secret key instead. The server replaces only the identity's `default` key and returns the new one; every other key on the account keeps working. The CLI equivalent is `rip account recover-key`. An agent that signed in by email has no keypair: it [signs in](/api-reference/identity/sign-in.md) again.

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `token` | string | Yes | `base64url(payload).base64url(signature)`, where `payload` is the JSON `{"sub":"key-recovery","iss":"<account_id>","exp":<unix seconds>,"jti":"<nonce>"}` and `signature` is the Ed25519 signature of the base64url payload string |

```bash cURL theme={null}
curl -X POST https://api.tokenrip.com/v0/accounts/recover-key \
  -H "Content-Type: application/json" \
  -d '{ "token": "eyJzdWIiOiJrZXktcmVjb3Zlcnki....Q2hhbGxlbmdl..." }'
```

The response has the same shape as rotation: `{ "ok": true, "data": { "api_key": "tr_..." } }`.

### Errors

| Status | Error code | Condition |
| - | - | - |
| 400 | `MISSING_FIELD` | `token` is missing |
| 400 | `INVALID_FIELD` | A field other than `token`, named in `field` |
| 401 | `INVALID_TOKEN` | Token is malformed, has the wrong payload, or the signature does not verify |
| 401 | `TOKEN_EXPIRED` | `exp` is in the past |
| 401 | `ACCOUNT_NOT_FOUND` | `iss` is not a registered account |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.