API Overview
Hosted verification endpoints for Emblem publishers.
This page covers Emblem's hosted verification API.
Base URL
Emblem currently operates a single public integration environment. Partners should integrate using production endpoints and issued API credentials.
| Environment | Base URL | Notes |
|---|---|---|
| Public integration | https://app.emblemapp.com | Use for hosted verification integrations and testing |
All API paths are relative to this base URL.
Authentication
Include your secret API key as a Bearer token:
Authorization: Bearer emb_sk_...For browser-initiated verification requests, you can use a public key. Only
POST /api/v1/verify/start accepts public key authentication. Result
validation and session reconciliation always require your secret key.
Public key is for browser or SDK use only
The public_key field in the /start request body is designed for
client-side SDK calls where a secret key cannot be safely embedded. If you are
making server-side API calls, use the Authorization: Bearer header with your
secret key and omit public_key from the body.
Provider compliance behavior such as SafePassage/PrivateAV face matching is
configured on the Integration in the Emblem dashboard, not in the /start
request. Use separate integrations for jurisdiction-specific behavior.
Rate limiting
Rate limits are enforced per IP address and per key:
| Auth method | Limit | Scope |
|---|---|---|
| Public key | 60 req/min | Per IP |
| Public key | 600 req/min | Per key |
| Secret key | 600 req/min | Per IP |
When a request is rate limited, Emblem returns 429 RATE_LIMITED and includes
a Retry-After header with the number of seconds to wait before retrying.
Verification endpoints
| Method | Path | Description |
|---|---|---|
POST | /api/v1/verify/start | Create a verification session and receive a redirect_url |
POST | /api/v1/verify/validate | Exchange a result_token for verification facts |
GET | /api/v1/verify/sessions/{sessionId} | Check the final state of a session for recovery and debugging |
Redirect contract
On successful verification, Emblem redirects to your callback_url with:
result_tokensession_idstateif you provided one when starting the session
The browser callback does not include the verification result itself. Your
server must call POST /api/v1/verify/validate to get the verification facts.
Failures do not return result tokens
Failed and expired sessions do not produce a result_token. Use
Webhooks for full lifecycle visibility.
Result token
Result tokens (emb_rt_...) are opaque strings returned only after successful
verification. They are:
- single-use
- valid for 5 minutes
- server-side only for validation
Call POST /api/v1/verify/validate as soon as you receive the callback.
Validate on your backend with the secret key
Send Authorization: Bearer emb_sk_* and only result_token in the JSON
body. Public keys authenticate /verify/start browser flows only; a public
key plus a result token cannot authenticate /verify/validate.
Use reconciliation only for recovery
GET /api/v1/verify/sessions/{sessionId} is a recovery endpoint for
operational debugging and missed callbacks. It does not replace POST /api/v1/verify/validate.