The RealShot documentation.

Integrate the API and badge.

Overview

RealShot exposes a small HTTP API and a lightweight badge component.

• Read status — public, no key required.
• Issue / revoke — privileged, require an API key.

All responses are JSON.

Authentication

Privileged endpoints require your API key in a header:

X-API-Key: <your-api-key>

Keep this key secret and server-side. Reading status needs no key.

Endpoints

Get status — GET /status/{subject}

Public. Returns the current verification state of a subject.

GET /status/alice

{
  "ok": true,
  "subject": "alice",
  "status": "verified",
  "version": 1,
  "as_of": "2026-05-31T12:05:31Z"
}

status is one of: verified, revoked, unknown.

Issue a verification — POST /issue

Requires API key. Marks a subject as verified and returns the signed object.

POST /issue
X-API-Key: <your-api-key>
Content-Type: application/json

{ "subject": "alice" }

{
  "ok": true,
  "envelope": {
    "payload": { "sub": "alice", "status": "verified", "ver": 1, "...": "..." },
    "alg": "ECDSA_P256_SHA256",
    "kid": "<signing-key-id>",
    "sig": "<signature>"
  }
}

Revoke a verification — POST /revoke

Requires API key. Withdraws a subject's verification immediately.

POST /revoke
X-API-Key: <your-api-key>
Content-Type: application/json

{ "subject": "alice" }

{ "ok": true, "subject": "alice", "status": "revoked", "version": 2 }

The verification object

Each verification is a signed envelope:

• payload — the verification state (subject, status, version, issue/expiry timestamps).
• alg — the signing algorithm.
• kid — which signing key was used.
• sig — the signature over the payload.

You can verify the signature locally using RealShot's public key. The signature proves the verification was validly issued — it does not prove current validity. Always check live status (or rely on the badge) for revocation.

The badge

Embed the badge to display a subject's status. It calls GET /status/{subject} on each render and shows the result.

• It contains no trust logic and cannot display "verified" without backend confirmation.
• Fail-closed: if the API is unreachable, it shows not verified rather than a stale "verified".

Best practices

• Treat the authoritative result as the live status, not a cached object.
• Never trust a verification result delivered from the user's browser; rely on server-side status.
• Re-check status when a user changes their profile photos (a verification is bound to the photos it was issued against).

What "Verified" means.

A RealShot Verified badge means this person completed a live face check and matched the photos on their profile. It confirms they are a real person who looks like their pictures — it helps prevent catfishing and stolen-photo profiles.

It does not verify someone's name, age, identity, or character. It is one safety signal, not a guarantee about who someone is.

How you get verified

1. You're asked to take a short live selfie (you may be prompted to move or turn).
2. It's compared to the photos on your profile.
3. If they match, your profile shows a Verified badge.

Your privacy

• RealShot does not collect your name, ID documents, date of birth, or age.
• The face check is used only to confirm you match your photos.
• Verification can be withdrawn if misuse is detected.

Badge states

• Verified — live check passed and matched the profile photos.
• Not verified — no current verification on record.
• Revoked — a previous verification was withdrawn.

Questions

• Why did my badge disappear? Changing your profile photos may require re-verification, since the badge is tied to the photos it was issued for.
• Is my face stored? Biometric processing is handled by a specialist verification provider; RealShot's own records store the verification result, not your photos.