Revoke a self-serve API key by emailed link

Endpoint#

POST /api/keys/revoke

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 revokes the key. Limited per IP and per address. Keys created from a signed-in account are managed on /account instead.

Authentication#

[]

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#

{
  "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. 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.

{
  "path": "/api/keys/revoke",
  "method": "POST",
  "parameters": [],
  "operationId": "revokeApiKey",
  "summary": "Revoke 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 revokes the key. 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/revoke' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"email\":\"you@example.com\"}'"
    }
  ]
}