API Walkthrough

Use the Terminal tab to interact directly with the CertChain REST APIs using curl.

Get an Access Token

First, obtain a Keycloak token for the TechPulse organization:

TOKEN=$(curl -sk -X POST \
  "https:///realms/techpulse/protocol/openid-connect/token" \
  -d "grant_type=password" \
  -d "client_id=course-manager-ui" \
  -d "username=admin@techpulse.demo" \
  -d "password=admin" | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
echo "Token: ${TOKEN:0:20}..."

Issue a Certificate

Generate a unique certificate ID and submit an issuance request:

# Generate a unique cert ID using timestamp
CERT_ID="API-$(date +%s)"

curl -sk -X POST \
  "https:///api/v1/certificates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"certID\": \"$CERT_ID\",
    \"studentID\": \"student01@techpulse.demo\",
    \"studentName\": \"Jane Doe\",
    \"courseID\": \"FSWD-101\",
    \"courseName\": \"Full-Stack Web Dev\",
    \"issueDate\": \"2026-03-01\",
    \"expiryDate\": \"2028-12-31\",
    \"grade\": \"A\",
    \"degree\": \"Professional Certificate\"
  }" | python3 -m json.tool
echo "Issued certificate: $CERT_ID"

Expected: HTTP 200 with the full certificate JSON including status: "ACTIVE".

Verify a Certificate (Public)

Query the public verify-api — no authentication needed:

curl -sk "https:///api/v1/verify/$CERT_ID" | python3 -m json.tool

The response includes status, student name, course, organization, and dates — but not grade or degree.

Batch Verify Multiple Certificates

Verify several certificates in a single request:

curl -sk "https:///api/v1/verify/batch?ids=$CERT_ID,FAKE-CERT-123" \
  | python3 -m json.tool

Each certificate returns its own status — VALID, REVOKED, or NOT_FOUND.

View Student Transcript (Cert Portal)

The transcript endpoints (/api/v1/transcript) require a token issued by Central Keycloak — the same token students get when they log into the Cert Portal through identity brokering.

To test this flow:

  1. Open the Cert Portal tab

  2. Click Login and select your organization (e.g., TechPulse)

  3. Sign in as student01@techpulse.demo / student

  4. The portal displays the student’s transcript — all certificates with grade and degree visible

The Cert Portal uses Central Keycloak’s identity brokering: the student authenticates at their org Keycloak, and Central Keycloak issues a federated token that verify-api accepts. This cannot be replicated with a simple curl password grant because federated users don’t have local credentials in Central Keycloak — by design.

List Certificates (Admin)

List all certificates issued by TechPulse with pagination:

curl -sk \
  "https:///api/v1/certificates?page=0&size=10" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

Dashboard Stats (Admin)

Get aggregate certificate statistics:

curl -sk \
  "https:///api/v1/dashboard/stats" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

Returns: totalCertificates, activeCertificates, revokedCertificates, expiredCertificates.

Update a Certificate

Update mutable fields on an existing certificate:

curl -sk -X PUT \
  "https:///api/v1/certificates/$CERT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "grade": "A+",
    "expiryDate": "2029-12-31"
  }' | python3 -m json.tool

Revoke a Certificate

curl -sk -X PUT \
  "https:///api/v1/certificates/$CERT_ID/revoke" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Demo revocation test"}' | python3 -m json.tool

After revocation, re-verify to confirm the status changed:

curl -sk "https:///api/v1/verify/$CERT_ID" | python3 -m json.tool

Expected: status: "REVOKED" with revokedDate and revokedReason fields.

Admin Role Enforcement

Try accessing the cert-admin-api without a valid admin token — it should be rejected:

# No token at all
curl -sk -o /dev/null -w "HTTP %{http_code}\n" \
  "https:///api/v1/certificates"

# With an invalid token
curl -sk -o /dev/null -w "HTTP %{http_code}\n" \
  "https:///api/v1/certificates" \
  -H "Authorization: Bearer invalid-token-here"

Expected: HTTP 401 — only users with the org-admin role can access admin endpoints.

Verify a Non-Existent Certificate

curl -sk "https:///api/v1/verify/does-not-exist" | python3 -m json.tool

Returns HTTP 404 with status: "NOT_FOUND".

API Reference

cert-admin-api (per-org, requires org-admin role)

Method Path Description

POST

/api/v1/certificates

Issue a new certificate

GET

/api/v1/certificates?page=0&size=20

List org certificates (paginated)

GET

/api/v1/certificates/{certId}

Get single certificate

PUT

/api/v1/certificates/{certId}

Update mutable fields

PUT

/api/v1/certificates/{certId}/revoke

Revoke (irreversible)

GET

/api/v1/courses

List course catalog

GET

/api/v1/dashboard/stats

Certificate stats

verify-api (central, public + JWT)

Method Path Auth Description

GET

/api/v1/verify/{certId}

Public

Verify certificate status

GET

/api/v1/verify/{certId}/qr

Public

Generate QR code (PNG)

GET

/api/v1/verify/batch?ids=X,Y

Public

Batch verify

GET

/api/v1/transcript

JWT

Student’s certificates

GET

/api/v1/transcript/{certId}

JWT

Single certificate