# Replace a self-serve API key by emailed link

replaceApiKey · POST /api/keys/replace

## Endpoint
`POST /api/keys/replace`

Send the address the key belongs to. The answer is always 202 status=check_email, whether or not the address holds a key, so the route cannot reveal who has one. If it does, that address is emailed a one-time link (30 minutes, single use) to /api/keys/confirm; opening it changes nothing, and confirming issues a new key (shown once on the confirmation page) and revokes the old one in one transaction, keeping its tier. Limited per IP and per address. Keys created from a signed-in account are managed on /account instead.

## Authentication
```json
[]
```
An empty security requirement means this operation does not declare authentication. Read operation notes for entitlement and protocol-method requirements.

## Parameters
No parameters declared by the specification.

## Request body
```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "description": "Where the key is emailed. One live key per address."
          }
        }
      },
      "example": {
        "email": "you@example.com"
      }
    }
  }
}
```

## Responses and errors
| HTTP status | Meaning |
| --- | --- |
| 202 | Always the same body: check the inbox the key belongs to. |
| 400 | code invalid_parameter: the body is not JSON or the email is not a valid address. |
| 429 | code rate_limited: too many requests from this network or for this address. Honour Retry-After. |

## Response examples
No response example is supplied by OpenAPI for this operation. The complete response schemas are preserved below; use an actual response for observed values.

## Retry guidance
See [errors and retries](/docs/api/overview#errors-and-retries). Honor operation-specific response headers. A POST may create state; do not replay it automatically.

## Complete operation contract
The expanded contract below includes all parameter constraints, response headers, schemas and examples from OpenAPI.

```json
{
  "path": "/api/keys/replace",
  "method": "POST",
  "parameters": [],
  "operationId": "replaceApiKey",
  "summary": "Replace a self-serve API key by emailed link",
  "description": "Send the address the key belongs to. The answer is always 202 status=check_email, whether or not the address holds a key, so the route cannot reveal who has one. If it does, that address is emailed a one-time link (30 minutes, single use) to /api/keys/confirm; opening it changes nothing, and confirming issues a new key (shown once on the confirmation page) and revokes the old one in one transaction, keeping its tier. Limited per IP and per address. Keys created from a signed-in account are managed on /account instead.",
  "tags": [
    "keys",
    "Manage access"
  ],
  "security": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "email"
          ],
          "properties": {
            "email": {
              "type": "string",
              "format": "email",
              "maxLength": 254,
              "description": "Where the key is emailed. One live key per address."
            }
          }
        },
        "example": {
          "email": "you@example.com"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Always the same body: check the inbox the key belongs to.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "ok",
              "status"
            ]
          }
        }
      }
    },
    "400": {
      "description": "code invalid_parameter: the body is not JSON or the email is not a valid address."
    },
    "429": {
      "description": "code rate_limited: too many requests from this network or for this address. Honour Retry-After."
    }
  },
  "x-codeSamples": [
    {
      "lang": "curl",
      "label": "curl",
      "source": "curl -s -X POST 'https://china-snapshot.com/api/keys/replace' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"email\":\"you@example.com\"}'"
    }
  ]
}
```