Workflows

Issue a single credential

Authenticate

curl -X POST https://api.certiva.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'

{ "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

The API also sets an httpOnly cookie (certiva_access_token). Dashboard requests use the cookie automatically — no manual header needed.

Submit the credential

curl -X POST https://api.certiva.io/api/credentials \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{
    "studentName": "Siti Rahayu",
    "studentId": "2020045678",
    "degree": "Bachelor of Computer Science",
    "graduationYear": 2024
  }'

{
  "id": "clx9k2...",
  "verificationId": "vrf_2f9a0cdbe7c1",
  "verificationCode": "CERT-A1B2C3",
  "verificationUrl": "https://certiva.io/verify/vrf_2f9a0cdbe7c1",
  "qrCodeUri": "https://api.certiva.io/api/credentials/<id>/qr",
  "anchorStatus": "PENDING",
  "issuedAt": "2024-06-01T08:00:00.000Z"
}

Share with the recipient

Give the credential holder the verificationCode, verificationUrl, or QR code. All three resolve to the same credential record.

Issue credentials in bulk (CSV)

Upload the CSV

curl -X POST https://api.certiva.io/api/credentials/bulk \
  -H "Authorization: Bearer <accessToken>" \
  -F "file=@credentials.csv"

{
  "batchId": "batch_8f3c...",
  "status": "QUEUED",
  "totalRows": 250
}

Poll batch progress

curl https://api.certiva.io/api/batches/batch_8f3c... \
  -H "Authorization: Bearer <accessToken>"

{
  "batchId": "batch_8f3c...",
  "status": "PROCESSING",
  "totalRows": 250,
  "processedRows": 143,
  "failedRows": 2
}

Poll until status is COMPLETED or FAILED. Failed rows include per-row error details.

Verify a credential publicly

No authentication required for any verification endpoint.

By verification code

curl -X POST https://api.certiva.io/api/verify/credential/code \
  -H "Content-Type: application/json" \
  -d '{"verificationCode": "CERT-A1B2C3"}'

{
  "verificationMode": "CORE_REGISTRY",
  "result": "VALID",
  "revoked": false,
  "degree": "Bachelor of Computer Science",
  "issuedAt": "2024-06-01T08:00:00.000Z",
  "issuer": { "name": "Universitas Contoh", "status": "ACTIVE" },
  "blockchainVerified": true,
  "txHash": "0x3a7f2e...c4d1b8",
  "blockNumber": 14203847,
  "anchoredAt": "2024-06-01T08:04:12.000Z"
}

By PDF upload

curl -X POST https://api.certiva.io/api/verify/credential/pdf \
  -F "file=@credential.pdf"

Rate limited to 10 requests per 60 seconds.

Register a document integrity proof

Upload the document

curl -X POST https://api.certiva.io/api/document-proofs \
  -H "Authorization: Bearer <accessToken>" \
  -F "file=@transcript.pdf"

{
  "id": "dp_7a3f...",
  "verificationCode": "DOC-X9Y8Z7",
  "qrCodeUri": "https://api.certiva.io/api/document-proofs/dp_7a3f.../qr"
}

Certiva hashes the document and discards the source file. Only the SHA-256 hash is stored.

Share the verification code

Give document holders the verificationCode or QR code. Anyone can verify the document has not been modified.

Verify a document proof publicly

curl -X POST https://api.certiva.io/api/document-proofs/verify/document \
  -F "file=@transcript.pdf" \
  -F "code=DOC-X9Y8Z7"

{
  "result": "VALID",
  "verificationMode": "SECURE_PDF"
}

Returns VALID on a byte-level hash match, INVALID if the file has been modified, or NOT_FOUND if no matching proof exists.

Revoke a credential

curl -X PATCH https://api.certiva.io/api/credentials/<id>/revoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{"reason": "DATA_CORRECTION"}'

Valid reasons: DATA_CORRECTION, ISSUED_IN_ERROR, FRAUD_SUSPECTED, INSTITUTION_REQUEST, OTHER, LEGACY. After revocation, public verification returns result: REVOKED permanently.

Bulk revoke

curl -X POST https://api.certiva.io/api/credentials/bulk-revoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{
    "ids": ["clx9k2...", "clx9k3..."],
    "reason": "INSTITUTION_REQUEST"
  }'

Create an admin account

Requires OWNER or SUPER_ADMIN role.

curl -X POST https://api.certiva.io/api/auth/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{
    "username": "auditor1",
    "password": "strong-password-here",
    "role": "AUDITOR"
  }'

Migrate assets from local storage to R2

A one-time migration script moves all credential assets from the local filesystem driver to Cloudflare R2. Run this once during the transition to staging or production:

cd apps/api
npx tsx scripts/migrate-assets-to-r2.ts

Run in a maintenance window with valid R2 credentials configured. Verify all assets are present in R2 before switching STORAGE_DRIVER=r2 in production.

Rebuild credential assets

If QR codes or metadata become stale after a URL configuration change:

curl -X POST https://api.certiva.io/api/credentials/<id>/rebuild-assets \
  -H "Authorization: Bearer <accessToken>"

Export audit logs

curl https://api.certiva.io/api/audit/dashboard/export \
  -H "Authorization: Bearer <accessToken>"

Start here

Product guide

API reference

Issue a single credential

Issue credentials in bulk (CSV)

Verify a credential publicly

By verification code

By PDF upload

Register a document integrity proof

Verify a document proof publicly

Revoke a credential

Bulk revoke

Create an admin account

Migrate assets from local storage to R2

Rebuild credential assets

Export audit logs

​Issue a single credential

​Issue credentials in bulk (CSV)

​Verify a credential publicly

​By verification code

​By PDF upload

​Register a document integrity proof

​Verify a document proof publicly

​Revoke a credential

​Bulk revoke

​Create an admin account

​Migrate assets from local storage to R2

​Rebuild credential assets

​Export audit logs

Issue a single credential

Issue credentials in bulk (CSV)

Verify a credential publicly

By verification code

By PDF upload

Register a document integrity proof

Verify a document proof publicly

Revoke a credential

Bulk revoke

Create an admin account

Migrate assets from local storage to R2

Rebuild credential assets

Export audit logs