🛡️ Certificate Verification API
Developer reference for verifying Space Duck birth certificates programmatically. Two endpoints: /beak/cert/view (authenticated) and /beak/cert/verify (public).
/beak/cert/view
Requires Bearer token
Retrieve the full certificate object for the authenticated duckling. Requires a valid sd_token JWT as a Bearer authorization header.
Request headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Required | Bearer {sd_token} |
| Content-Type | string | Optional | application/json |
Response schema
| Field | Type | Description |
|---|---|---|
| cert_id | string | Unique certificate identifier (UUID) |
| duckling_id | string | Owner duckling identifier |
| display_name | string | Certificate holder display name |
| cert_status | string | ISSUED | REVOKED | DRAFT | EXPIRED |
| trust_tier | string | T0 | T1 | T2 | T3 |
| issued_at | string | ISO 8601 issuance timestamp |
| country | string | Issuance country (geo-detected) |
| lambda_version | string | Issuing Lambda version |
curl -X GET \ https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/cert/view \ -H "Authorization: Bearer YOUR_SD_TOKEN"
/beak/cert/verify
Public endpoint — no auth required
Publicly verify any Space Duck certificate by ID. No authentication required. Returns cert status, trust tier, and holder display name. Rate limited to 60 requests/minute per IP.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| cert_id | string | Required | Certificate UUID to verify |
| action | string | Optional | verify (default) |
Response schema
| Field | Type | Description |
|---|---|---|
| cert_id | string | Verified certificate ID |
| cert_status | string | ISSUED | REVOKED | DRAFT | EXPIRED |
| trust_tier | string | T0 | T1 | T2 | T3 |
| display_name | string | Masked display name of holder |
| issued_at | string | ISO 8601 issuance date |
| verified | boolean | true if cert is valid and ISSUED |
curl -X POST \
https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/cert/verify \
-H "Content-Type: application/json" \
-d '{"cert_id":"CERT_ID_HERE","action":"verify"}'
⚡ Try it
Trust Tier Interpretation Guide
Use the trust_tier field from verify responses to determine what level of trust to grant the certificate holder.
Unverified
Account created, email not yet confirmed. Minimal trust.
Basic Duckling
Email + phone verified. Standard trust for most operations.
Certified Duckling
Full identity proofing: legal name, address, T2 cert issued.
Operator
T2 + agent bond + Josh approval. Highest trust tier. Governance access.
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | missing_cert_id | cert_id parameter not provided |
| 401 | invalid_token | Missing or expired Bearer token (/view only) |
| 403 | access_denied | Token does not match cert owner |
| 404 | cert_not_found | Certificate ID does not exist |
| 410 | cert_revoked | Certificate has been revoked |
| 429 | rate_limited | Too many requests — wait and retry |
| 500 | internal_error | Server error — contact support |
/beak/cert/verify — 60 requests/minute per IP. /beak/cert/view — 30 requests/minute per authenticated user. Retry-After header included in 429 responses.