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

# Renewal and revocation

> What renews on its own, what does not, how revoking differs from deleting, and every status a certificate can hold.

## Renewal

Certificates the platform issued are renewed automatically, starting **30 days
before `expires_at`**. The window is deliberately wide: it leaves room for many
attempts before anything actually expires, so a transient DNS or authority
problem is not an outage.

Renewal reuses the existing challenge delegation, so a CNAME you published once
keeps working. When a certificate is reissued its `fingerprint` changes — that
is the signal to anything holding the material that there is a new generation to
pick up.

A renewal that fails is retried, but not immediately: a certificate whose last
attempt was under six hours ago is skipped, so a stuck CNAME or an authority
having a bad day is retried on a sensible cadence rather than on every pass.

<Info>
  Uploaded certificates are excluded from renewal. See
  [Uploading your own certificate](/certificates/uploading).
</Info>

## Revoking

```bash theme={null}
POST /v1/certificates/{certificate_id}/revoke
```

<Note>
  Revocation is **API only**. The console's action on a certificate is
  **Delete certificate**, which is a different thing: deleting removes the
  certificate from your account, while revoking asks the issuing authority to
  mark it invalid so clients that check revocation stop trusting it. If the
  private key may have leaked, revoke — deleting alone leaves a certificate
  that still validates.
</Note>

Revocation is asynchronous: the call returns **`202`** with the certificate
still in its previous state, and you poll until `status` is `revoked`. An
uploaded certificate is revoked locally, without contacting an authority.
Revoking something already revoked is a no-op, not an error.

## Statuses

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending: create (acme)
    [*] --> active: create (uploaded)
    pending --> pending_dns: challenges planned
    pending_dns --> active: every challenge verified
    pending_dns --> error: validation deadline passed
    pending --> error: issuance failed
    active --> revoked: revoke
    active --> expired: expires_at reached
```

| Status        | Meaning                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------- |
| `pending`     | Created; the issuance workflow has not planned challenges yet. `challenges` is empty.         |
| `pending_dns` | Waiting on DNS. One `challenges` entry per domain; issuance proceeds when all are `verified`. |
| `active`      | Signed and usable. `certificate_pem`, `fingerprint` and `expires_at` are set.                 |
| `error`       | Issuance failed. Read `error_message`.                                                        |
| `expired`     | Passed `expires_at` without a successful renewal.                                             |
| `revoked`     | Revocation completed.                                                                         |