# Revocation (https://developer.godaddy.com/en/docs/references/rest/ans/revocation)

***

title: Revocation
description: ''
full: true
\_openapi:
method: POST
toc:

* depth: 2
  title: Revoke an active agent or cancel a pending registration
  url: '#revoke-an-active-agent-or-cancel-a-pending-registration'
  structuredData:
  headings:
  * content: Revoke an active agent or cancel a pending registration
    id: revoke-an-active-agent-or-cancel-a-pending-registration
    contents:
  * content: >
    Revokes an active agent or cancels a pending registration.

    For ACTIVE agents: Revokes the agent due to key compromise,
    decommissioning,

    or other security reasons. The certificate is added to the Certificate

    Revocation List (CRL) and the agent's entry in the registry is
    flagged.

    For PENDING registrations (PENDING\_CERTS or PENDING\_DNS status):
    Cancels

    the registration attempt after domain validation has been completed.
    This

    will cancel any pending certificate issuance jobs and revoke any
    already-issued

    certificates.

    Registrations in PENDING\_VALIDATION status (pre-ACME verification)

    are not cancellable via this API and will automatically expire if the

    ACME verification is not completed within the specified timeframe.
    heading: revoke-an-active-agent-or-cancel-a-pending-registration

***

## POST /v1/agents/{agentId}/revoke

Revoke an active agent or cancel a pending registration

Revokes an active agent or cancels a pending registration.

For ACTIVE agents: Revokes the agent due to key compromise, decommissioning,
or other security reasons. The certificate is added to the Certificate
Revocation List (CRL) and the agent's entry in the registry is flagged.

For PENDING registrations (PENDING_CERTS or PENDING_DNS status): Cancels
the registration attempt after domain validation has been completed. This
will cancel any pending certificate issuance jobs and revoke any already-issued
certificates.

Registrations in PENDING_VALIDATION status (pre-ACME verification)
are not cancellable via this API and will automatically expire if the
ACME verification is not completed within the specified timeframe.


### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `agentId` | string | yes | Unique identifier of the agent |

### Request body (required)

Agent revocation request

Content-Type: `application/json`

Schema:

- object — Agent revocation request
  - `reason` (required): string — Reason for revocation
    - enum: "KEY_COMPROMISE", "CESSATION_OF_OPERATION", "AFFILIATION_CHANGED", "SUPERSEDED", "CERTIFICATE_HOLD", "PRIVILEGE_WITHDRAWN", "AA_COMPROMISE"
  - `comments`: string — Additional comments about revocation

### Responses

**200** — Agent certificate revoked successfully

Content-Type: `application/json`

Schema:

- object — Agent revocation response
  - `agentId` (required): string <uuid> — The agent that was revoked
  - `ansName` (required): string — The ANS name that was revoked
  - `status` (required): string — Status of an agent in its registration and operational lifecycle
    - enum: "PENDING_VALIDATION", "PENDING_DNS", "ACTIVE", "FAILED", "EXPIRED", "REVOKED"
  - `revokedAt` (required): string <date-time> — When the revocation occurred
  - `reason` (required): string — Reason for revocation
    - enum: "KEY_COMPROMISE", "CESSATION_OF_OPERATION", "AFFILIATION_CHANGED", "SUPERSEDED", "CERTIFICATE_HOLD", "PRIVILEGE_WITHDRAWN", "AA_COMPROMISE"
  - `links` (required): array — HATEOAS links for related operations
      - items:
          - `href` (required): string <uri> — Link URL
          - `rel` (required): string — Link relation type
  - `dnsRecordsToRemove`: array — DNS records that should be removed by the AHP following revocation. Includes records like _ra-badge, _ans, TLSA, and HTTPS service binding records that were provisioned during registration.
      - items:
          - `name` (required): string — Full DNS record name
          - `priority`: integer — For HTTPS records
          - `purpose`: string — Purpose of this DNS record
            - enum: "DISCOVERY", "TRUST", "CERTIFICATE_BINDING", "BADGE"
          - `required`: boolean — Whether this record is required
          - `ttl`: integer
          - `type` (required): string
            - enum: "HTTPS", "TLSA", "TXT"
          - `value` (required): string — Record value to set

**401** — Authentication failed

Content-Type: `application/json`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**403** — Authorization failed

Content-Type: `application/json`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**404** — Agent not found

Content-Type: `application/json`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**422** — Invalid revocation request (semantic validation failure). Common scenarios: Agent is in DEPRECATED, REVOKED, or EXPIRED state (only ACTIVE or PENDING can be revoked); Attempting to use SUPERSEDED reason (reserved for internal deprecation flow); Agent is in PENDING_VALIDATION state (will automatically expire if verification not completed)

Content-Type: `application/json`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**500** — Internal server error

Content-Type: `application/json`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"