Skip to main content

​
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 values

StatusDescription
draftCertificate is being prepared. Not yet publicly verifiable.
issuedCertificate has been officially issued. The verification URL is active.
revokedCertificate was revoked after issuance. The verification URL shows a revocation notice.
expiredCertificate has passed its validity date (if one was set).

​
State transitions

         ┌─────────────────────────────────┐
         │                                 ▼
[draft] ──────────────────────────────> [issued]
                                            │
                                            ▼
                                       [revoked]

[issued] ──> [expired]   (automatic, if expiry is configured)
State transitions are one-way. A revoked certificate cannot be reinstated. A revoked or expired certificate cannot return to issued. If a certificate was revoked in error, you must issue a new one.

​
Creating in draft vs. issued

When calling POST /certificates, set status to control the initial state: 
// Creates a draft — not yet visible on verification URL
{ "status": "draft", ... }

// Creates and immediately issues — verification URL active
{ "status": "issued", "issued_at": "2024-12-01T00:00:00Z", ... }
Use draft when you want to stage certificates for a batch review before official publication.

​
Revoking a certificate

Call PUT /certificates/{uuid}/revoke with an optional reason: 
curl -X PUT https://api.dokstamp.eu/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

​
Public verification

When a certificate is in issued status, the public_verification_url field is populated: 
{
  "uuid": "a1b2c3d4-...",
  "status": "issued",
  "public_verification_url": "https://verificar.dokstamp.eu/a1b2c3d4",
  "issued_at": "2024-12-01T00:00:00.000000Z"
}
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. This is consistent with Verifiable Credentials (VC) standards, where the credential subject data must reflect what was true at issuance time.

​
Blockchain anchoring

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