SecureStamp API
REST API for trust verification, domain registry, stamp management and plugin analytics. All responses are JSON. Rate limits are per API key unless noted otherwise.
Authentication
Pass your API key in the Authorization header as a Bearer token, or as the X-API-Key header.
# Bearer token
curl -H "Authorization: Bearer sk_live_yourkey..." \
https://securestamp.online/api/trust/check
# API Key header
curl -H "X-API-Key: sk_live_yourkey..." \
https://securestamp.online/api/trust/checkAPI keys are prefixed sk_live_ (production) or sk_test_ (test). Generate them from your dashboard → API Keys.
Public endpoints
No auth — origin check, registry lookup, public receipts
Authenticated
API key required — tenant-scoped action and agent calls
Rate limits
60 req/min public · 300 req/min authenticated
Origin Check
/api/trust/checkVerify the origin status of an email address or domain before acting. Returns a score, trust state, registered-origin signals and SPF/DKIM/DMARC breakdown.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| target | string | ✓ | Email address or domain origin to verify |
Request body
{
"target": "newsletter@example.com"
}Response
{
"target": "newsletter@example.com",
"domain": "example.com",
"trustState": "CONFIABLE",
"score": 87,
"signals": {
"spf": "pass",
"dkim": "pass",
"dmarc": "pass",
"domainAge": "2y",
"registrationVerified": true,
"domainVerifiedInRegistry": true
},
"stamp": {
"stampId": "f47ac10b-...",
"artworkUrl": "https://securestamp.online/api/stamps/embed?id=f47ac...",
"collectionTitle": "Classic"
},
"checkedAt": "2026-06-02T18:00:00Z"
}cURL example
curl -X POST https://securestamp.online/api/trust/check \
-H "Content-Type: application/json" \
-d '{"target":"newsletter@example.com"}'Domain Registry
/api/registry/lookupCheck whether a domain is registered as a verifiable origin in the SecureStamp public registry. Returns registration date, score, and stamp status without exposing internal user data.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| domain | string (query) | ✓ | Domain to look up, e.g. example.com |
Response
{
"domain": "example.com",
"registered": true,
"score": 92,
"status": "CONFIABLE",
"registeredAt": "2025-03-14T10:00:00Z",
"hasActiveStamp": true
}cURL example
curl "https://securestamp.org/api/registry/lookup?domain=example.com"
Stamps
/api/stamps/embedAPI KeyReturns an HTML/SVG stamp widget for embedding in outgoing communications. The stamp is visual; validity still depends on token, registry and real-time verification.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string (query) | ✓ | Stamp ID returned by trust/check |
| theme | string (query) | — | "light" | "dark" (default: "dark") |
Response
<!-- Signed HTML trust stamp --> <div class="ss-stamp" data-stamp-id="f47ac10b..." data-score="87"> <img src="..." alt="SecureStamp verified" /> <a href="https://securestamp.org/verify/eyJhbG...">Verify</a> </div>
cURL example
curl "https://securestamp.online/api/stamps/embed?id=f47ac10b..." \ -H "Authorization: Bearer sk_live_yourkey..."
User & Quota
/api/quota/statusAPI KeyReturns the authenticated user's current quota usage, plan tier, and remaining verifications for the current billing period.
Response
{
"plan": "starter",
"billingInterval": "monthly",
"quota": {
"used": 142,
"limit": 1000,
"remaining": 858,
"resetAt": "2026-07-01T00:00:00Z"
}
}cURL example
curl https://securestamp.online/api/quota/status \ -H "Authorization: Bearer sk_live_yourkey..."
/api/user/artistAPI KeySelect an artist collection to display on outgoing stamps. A 10% subscription commission will accrue to the selected artist while the user has an active paid plan.
Request body
{
"artistId": "artist-uuid-or-cognito-sub"
}Response
{
"ok": true,
"selectedArtistId": "artist-uuid",
"artistSelectedAt": "2026-06-02T18:00:00Z"
}cURL example
curl -X PATCH https://securestamp.online/api/user/artist \
-H "Authorization: Bearer sk_live_yourkey..." \
-H "Content-Type: application/json" \
-d '{"artistId":"artist-uuid"}'/api/eventsRecord an anonymous plugin analytics event. No PII — only plan tier, event name, and risk metadata. Events are retained for 90 days.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| event | string | ✓ | Snake_case event name, e.g. plugin_signature_inserted |
| source | enum | ✓ | gmail | outlook | safari | apple-mail | cli | browser-extension |
| planTier | string | ✓ | User plan tier at the time of event |
| riskLevel | enum | — | safe | suspicious | dangerous |
| senderTrustState | enum | — | trusted | suspicious | high_risk | unknown |
| locale | string | — | BCP-47 locale, e.g. es-AR |
| timestamp | number | ✓ | Unix timestamp (ms) |
Request body
{
"event": "plugin_signature_inserted",
"source": "gmail",
"planTier": "free",
"locale": "es-AR",
"timestamp": 1748880000000
}Response
{
"ok": true,
"eventId": "uuid-..."
}cURL example
curl -X POST https://securestamp.online/api/events \
-H "Content-Type: application/json" \
-d '{"event":"plugin_signature_inserted","source":"gmail","planTier":"free","timestamp":1748880000000}'Error Codes
| Status | Code | Meaning |
|---|---|---|
| 400 | BAD_REQUEST | Malformed JSON or missing required field |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 422 | VALIDATION_ERROR | Input failed Zod schema validation |
| 429 | RATE_LIMITED | Too many requests — back off and retry |
| 503 | STORAGE_UNAVAILABLE | Temporary DynamoDB write failure |
| 502 | UPSTREAM_ERROR | Upstream Stripe or external service error |