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

# Certificate Lifecycle

> How certificates move through draft, issued, revoked, and expired states.

# Certificate Lifecycle

Every certificate in DokStamp has a `status` field that governs what actions can be performed on it and how it appears to the public. Status transitions are managed internally by the platform.

***

## Status values

| Status    | Description                                                                             |
| --------- | --------------------------------------------------------------------------------------- |
| `draft`   | Certificate is being prepared. Not yet publicly verifiable.                             |
| `issued`  | Certificate has been officially issued. The verification URL is active.                 |
| `revoked` | Certificate was revoked after issuance. The verification URL shows a revocation notice. |
| `expired` | Certificate has passed its validity date (if one was set).                              |

***

## State transitions

```
[draft] ──── finish: true ────► [issued]
                                    │
                                    ▼
                               [revoked]

[issued] ──► [expired]   (automatic, based on validity period)
```

<Warning>
  State transitions are **one-way**. A revoked certificate cannot be reinstated. If a certificate was revoked in error, you must issue a new one.
</Warning>

***

## Issuing a certificate

To transition a certificate from `draft` to `issued`, pass `finish: true` when creating it. This triggers the full issuance pipeline: file signing, academic transcript generation, and student notification.

```bash theme={null}
curl -X POST https://api.dokstamp.com/certificates \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: {TENANT}" \
  -d '{
    "institution_uuid": "...",
    "course_uuid": "...",
    "student_uuid": "...",
    "file_uuid": "...",
    "finish": true
  }'
```

Omitting `finish` (or passing `false`) creates the certificate as a `draft`, allowing review before official publication.

***

## Revoking a certificate

Call `PUT /certificates/{uuid}/revoke` with an optional reason:

```bash theme={null}
curl -X PUT https://api.dokstamp.com/certificates/{uuid}/revoke \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: {TENANT}" \
  -d '{ "revocation_reason": "Issued in error — student did not complete requirements." }'
```

After revocation, the public verification URL remains accessible but displays a clear revocation notice with the reason and timestamp.

→ [Full revocation reference](/en/api-reference/certificates/revocation)

***

## Public verification

When a certificate is in `issued` status, the `public_verification_url` field is populated:

```json theme={null}
{
  "uuid": "a1b2c3d4-...",
  "status": "issued",
  "public_verification_url": "https://verificar.dokstamp.eu/a1b2c3d4"
}
```

This URL can be shared with employers, other institutions, or included in the printed certificate as a QR code. No authentication is required to access it.

***

## Credential Subject Snapshot

At the time a certificate is issued, DokStamp captures a **snapshot** of the student's identity data (name, email, document ID, date of birth, country). This snapshot is stored immutably alongside the certificate so that the credential remains verifiable even if the student's profile is later updated.

***

## Blockchain anchoring

Certificates include optional `blockchain_tx_hash` and `blockchain_tx_url` fields for blockchain anchoring. When set, these provide tamper-evident proof that the certificate was recorded on a public ledger at a specific point in time.