Device Uniqueness Backend API Reference

01

Validation Flow

#

The iOS smoke drives this sequence end-to-end. Each step gates the next.

POST /api/v1/auth/challenges — challenge
POST /api/v1/auth/app-attest/attestations — returns 202 {} no-op
POST /api/v1/auth/token — sr25519 proof → JWT
POST /api/v1/usernames/available?version=v1 — JWT-gated chain read
POST /api/v1/usernames — 202 outbox reservation

The full write path is verified end-to-end on this deployment (2026-07-09): a real-signature registration returned 202, was drained by the chain-writer (proxy-signed PeopleLite.attest), and finalized on People Chain — confirmed in Resources.UsernameOwnerOf. Invalid or dummy attestation payloads are still rejected by the runtime.

02

Liveness & Readiness

#

GET /healthcheck

200 public

Process health probe. No dependencies checked.

Response · 200 · application/json

json

{
  "status": "ok",
  "service": "device-attestation"
}

200 OK

Process is up. No dependencies checked.

GET /livez

200 public

Kubernetes liveness probe — "should this pod be restarted".

Response · 200 · application/json

json

{
  "status": "alive",
  "service": "device-attestation"
}

200 OK

Process is alive.

GET /readyz

200 503 public

Kubernetes readiness probe — checks db and chain subsystems.

Response · 200 · application/json

json

{
  "status": "ready",
  "service": "device-attestation",
  "db": "up",
  "chain": "up"
}

Response · 503 · application/json

json

{
  "status": "unavailable",
  "service": "device-attestation",
  "db": "down"
}

200 OK

Instance can take traffic; db and chain reachable.

503 UNAVAILABLE

A required subsystem is unavailable.

03

Discovery

#

GET /.well-known/jwks.json

200 public

Publish the Ed25519 public key so siblings can verify tokens.

Response · 200 · application/json

json

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "use": "sig",
      "alg": "EdDSA",
      "kid": "...",
      "x": "..."
    }
  ]
}

200 OK

JWT verification keyset (Ed25519 / OKP).

GET /api/v1/attester

200 public

GET /api/v1/attester — the attester authority public key (0x+hex, public).

Response · 200 · application/json

json

{
  "attester": "0xe4cd20d6d1e0e119d63a943afd2d7496fbbb0ac8e7cd99c3c5f16b63a68e7432"
}

200 OK

The on-chain attester account the backend writes as.

04

Authentication

#

POST /api/v1/auth/app-attest/attestations

202 401 public

Register an App Attest key: verify the attestation object and persist the credential key (no-op 202 {} while AUTH_ENABLED=false).

Field	Type	Required	Description
keyId	string	yes	Base64 key identifier (SHA-256 of the credential public key).
challenge	string	yes	Base64 challenge previously returned from `/auth/challenges`.
attestation	string	yes	Base64 CBOR attestation object from the platform.

Request Body

json

{
  "keyId": "s/134MbeEEZDZKCvOTf+jZgNhpoDwdXZ8cKfTym8FUg=",
  "challenge": "challenge-from-/auth/challenges",
  "attestation": "base64-attestation-object"
}

Response · 202 · application/json

json

{}

Response · 401 · application/json

json

{
  "_tag": "VERIFY_ATTESTATION_FAILED",
  "error": "attestation nonce mismatch"
}

202 ACCEPTED

Accepted. With attestation enabled, the key is verified against Apple and stored; while disabled, the payload is not verified.

401 attestation nonce mismatch

Attestation rejected (hard mode), or the challenge was unknown, expired, or already used. Soft mode logs failed verdicts and returns 202.

POST /api/v1/auth/challenges

201 public

Issue a fresh single-use challenge (201).

Response · 201 · application/json

json

{
  "challenge": "base64-32-byte-challenge"
}

201 CREATED

A fresh single-use challenge. No body required.

POST /api/v1/auth/token

200 401 403 503 public

Verify challenge + client proof and issue an access + refresh token pair.

Header	Type	Required	Description
Auth-ClientId	string	yes	Base64 of the 32-byte sr25519 public key.
Auth-ClientProof	string	yes	Base64 of the 64-byte sr25519 signature over the raw body.
Auth-Challenge	string	yes	Challenge previously minted via /auth/challenges.
Auth-iOS-Package	string	no	iOS bundle id, e.g. io.pcf.polkadotapp. Selects the App Attest verification path.
Auth-Payload	string	no	Base64 App Attest assertion (iOS) or the raw classic Play Integrity token (Android play-integrity), verified when attestation is enabled.
Auth-iOS-KeyId	string	no	Base64 App Attest key id registered via /auth/app-attest/attestations.
Auth-Android-Package	string	no	Android package name; required for play-integrity and sets the JWT platform claim for Android clients.
Auth-Attestation-Type	string	no	Android attestation dispatch: `key-attestation` verifies the `attestationChain` field in the JSON body (base64 DER, leaf first), and also sets the Android platform claim when Auth-Android-Package is absent; `play-integrity` verifies the token in Auth-Payload with self-managed response keys.

Request Body

json

{}

Response · 200 · application/json

json

{
  "token": "jwt",
  "refreshToken": "opaque-base64-token"
}

Response · 401 · application/json

json

{
  "error": "UNAUTHORIZED",
  "message": "unauthorized"
}

Response · 403 · application/json

json

{
  "error": "INTEGRITY_FAILED",
  "message": "attestation rejected"
}

Response · 503 · application/json

json

{
  "error": "ATTESTATION_CRL_UNAVAILABLE",
  "message": "attestation CRL unavailable"
}

200 OK

Verified. Access JWT + opaque refresh token.

401 UNAUTHORIZED

Bad or spent challenge, or invalid client proof.

403 INTEGRITY_FAILED

Platform attestation failed verification (hard enforcement).

503 ATTESTATION_CRL_UNAVAILABLE

Android attestation revocation list unavailable; retry with a fresh challenge (hard enforcement).

POST /api/v1/auth/token/refresh

200 401 public

Rotate a refresh token, returning a fresh access + refresh pair.

Field	Type	Required	Description
refreshToken	string	yes	Opaque refresh token issued by `/auth/token` or a prior refresh.

Request Body

json

{
  "refreshToken": "opaque-base64-token"
}

Response · 200 · application/json

json

{
  "token": "jwt",
  "refreshToken": "new-opaque-base64-token"
}

Response · 401 · application/json

json

{
  "error": "UNAUTHORIZED",
  "message": "unauthorized"
}

200 OK

Rotated. New access JWT + new opaque refresh token.

401 UNAUTHORIZED

Unknown, expired, or already-spent refresh token.

05

Usernames

#

GET /api/v1/registration/queue

200 401 404 429 bearer JWT

Queue standing for the caller's pending username claim. This route exists only on deployments with the registration queue enabled (QUEUE_ENABLED); with the queue disabled the path serves the standard plain-text 404. Clients should treat ANY 404 here as "not (or no longer) queued" and assume the registration is proceeding — queued claims keep draining even if the queue is later disabled. When an account has several queued claims, the response reports the earliest-enqueued one until it drains.

Auth Bearer JWT required in the Authorization header.

Response · 200 · application/json

json

{
  "queuePosition": 17,
  "group": 2,
  "estimatedIterationsRemaining": 5
}

Response · 404 · application/json

json

{
  "error": "No queue entry found"
}

200 OK

The caller's queued claim: position, priority group, and the estimated advancer iterations until it is promoted for on-chain registration.

401 UNAUTHORIZED

Missing or invalid bearer token.

404 No queue entry found

The account has no queued registration (JSON body), or the deployment runs queue-disabled (plain-text body). Either way: stop polling, the claim is proceeding without the queue.

429 RATE_LIMITED

Subject rate limit exceeded (with Retry-After).

POST /api/v1/usernames

200 202 400 401 403 409 429 500 502 503 bearer JWT

Reserve a lite username and enqueue it for on-chain registration.

Auth Bearer JWT required in the Authorization header.

Field	Type	Required	Description
candidateAccountId	string	yes	SS58 beneficiary account that will own the username.
username	string	yes	Base username (lowercase ASCII letters, 6..=29 chars).
preferredDigits	string	no	Optional two-digit suffix, e.g. `"07"`; random-free if omitted.
candidateSignature	string	yes	`0x`-hex 64-byte sr25519 signature proving control of the candidate.
ringVrfKey	string	yes	`0x`-hex ring VRF key.
proofOfOwnership	string	yes	`0x`-hex 64-byte ownership proof.
consumerRegistrationSignature	string	yes	`0x`-hex 64-byte consumer registration signature.
identifierKey	string	yes	`0x`-hex 65-byte identifier key.
lifetimePoUDVoucher	string	no	Optional single-use registration voucher (the INSTANT lane): bypasses the PoUD gate and the registration queue. Ignored unless `REGISTRATION_VOUCHERS_ENABLED`.
attestationChain	string[]	no	Optional Android device-uniqueness evidence (Widevine PoUD): leaf-first base64 DER attestation chain, 2-10 entries, whose leaf key was created with `attestationChallenge = SHA-256(domain ‖ deviceChallenge ‖ accountKey ‖ deviceId)`. All three evidence fields are present together or not at all; ignored unless `WIDEVINE_DEDUP_ENABLED`. Sent only when the app measured Widevine L1.
deviceChallenge	string	no	Base64 32-byte single-use challenge from `/auth/challenges`, bound into the leaf key's attestation challenge.
deviceId	string	no	Base64 32-byte device pseudonym: `SHA-256("dub/poud/widevine-id/v1" ‖ rawWidevineId)`, computed on the device — the raw id never leaves it.
dotns	object	no

dotns.*	Type	Required	Description
signature	string	yes	`0x`-hex 64-byte signature.
signedAt	number	yes	Unix timestamp the reservation was signed at.
reservedUsername	string	no	The bare personhood name to reserve. Its own name on chain — it need not be `username`, and availability is checked against this name, not against the base of the lite username in the same claim.

Request Body

json

{
  "candidateAccountId": "5FbRAkhDvNVecNzHLFxBNXFXNwvBaV69S1W3nfBbnxYypkkT",
  "username": "tallesx",
  "preferredDigits": "07",
  "candidateSignature": "0x...64 bytes...",
  "ringVrfKey": "0x...",
  "proofOfOwnership": "0x...64 bytes...",
  "consumerRegistrationSignature": "0x...64 bytes...",
  "identifierKey": "0x...65 bytes...",
  "lifetimePoUDVoucher": "base64url-voucher-key",
  "attestationChain": [
    "base64-der-leaf",
    "base64-der-root"
  ],
  "deviceChallenge": "base64-32-byte-challenge",
  "deviceId": "base64-32-byte-device-id",
  "dotns": {
    "signature": "0x...64 bytes...",
    "signedAt": 1780000000,
    "reservedUsername": "reservedname"
  }
}

Response · 200 · application/json

json

{
  "registrationOutcome": "PAYMENT_REQUIRED"
}

Response · 202 · application/json

json

{
  "base_username": "tallesx",
  "digits": "07",
  "username": "tallesx.07"
}

Response · 400 · application/json

json

{
  "error": "The request body contains invalid values.",
  "fields": [
    {
      "field": "candidateSignature",
      "message": "Invalid signature."
    }
  ]
}

Response · 403 · application/json

json

{
  "error": "DEVICE_EVIDENCE_INVALID",
  "message": "device evidence invalid"
}

Response · 409 · application/json

json

{
  "error": "Preferred digits 07 already taken for username tallesx"
}

Response · 500 · application/json

json

{
  "error": "Failed to persist username registration"
}

Response · 502 · application/json

json

{
  "error": "iOS DeviceCheck verification failed"
}

Response · 503 · application/json

json

{
  "error": "Failed to mark iOS device as registered with Apple DeviceCheck"
}

200 OK

The device is not eligible for a free registration: hard-mode DeviceCheck found its free slot already used, enforced Widevine dedup found the device already recorded or the Android claim carried no evidence, or a concurrent claim won the device's slot. Not an error — a 200 outcome, and a terminal one: no claim is stored and there is no paid alternative. The value PAYMENT_REQUIRED is historical (the retired paid lane) and kept for client compatibility.

202 ACCEPTED

Reservation accepted into the outbox for on-chain registration. With the registration queue enabled (QUEUE_ENABLED) and the queue service live, the claim waits in the balance-priority queue and the body additionally carries registrationOutcome: "QUEUED" plus the claim's queue standing (poll GET /api/v1/registration/queue for updates). A down queue service falls back to the direct registration path (no queue fields). With REGISTRATION_VOUCHERS_ENABLED, a valid lifetimePoUDVoucher bypasses the device gate and the queue: the reservation goes straight to the writer and the body carries registrationOutcome: "INSTANT".

400 The request body contains invalid values.

Validation failed (with per-field fields), malformed JSON, a lifetimePoUDVoucher that is unknown, already used, or expired ({"error": "Voucher already used"} — a voucher failure rejects the claim outright), or — with WIDEVINE_DEDUP_ENFORCE — structurally malformed device evidence ({"error": "DEVICE_EVIDENCE_MALFORMED"}: partial fields, bad base64, or wrong field sizes — the specific reason is logged server-side, never returned).

401 UNAUTHORIZED

Missing or invalid bearer token, or hard-mode DeviceCheck required a usable Device-Token-iOS and none was present.

403 DEVICE_EVIDENCE_INVALID

Device evidence failed verification under WIDEVINE_DEDUP_ENFORCE: chain policy, the cert-bound evidence hash (challenge / account / deviceId), or a spent challenge. The specific reason is logged server-side, never returned. Retryable once with a fresh challenge; a claim retried without evidence gets the 200 ineligible outcome.

409 Preferred digits 07 already taken for username tallesx

Preferred digits taken, no digits available, username taken, or the claim carries dotns.reservedUsername for a personhood name that is already owned or whose reservation queue is full — checked against the reserved name itself, which attest takes as its own argument and which need not be username. The runtime checks that leg *before* it writes the lite username, and the consumer signature covers it, so submitting would cost the whole registration and no server-side retry could rescue it. Re-sign for another dotns.reservedUsername.

429 RATE_LIMITED

Subject rate limit exceeded (with Retry-After).

500 Failed to persist username registration

Persistence failure or unexpected error.

502 iOS DeviceCheck verification failed

Hard-mode DeviceCheck could not reach Apple to resolve the device.

503 Failed to mark iOS device as registered with Apple DeviceCheck

The DeviceCheck free slot could not be marked used at Apple after a successful gate (upstream write failure; retryable), or the enforced Widevine dedup gate could not fetch the attestation revocation list (DEVICE_EVIDENCE_UNAVAILABLE; retryable).

POST /api/v1/usernames/available

200 400 401 429 500 bearer JWT

Availability for each requested base.

Auth Bearer JWT required in the Authorization header.

Field	Type	Required	Description
usernames	string[]	yes	Candidate base usernames to validate and check (max 100).

Request Body

json

{
  "usernames": [
    "tallesx",
    "abc"
  ]
}

Response · 200 · application/json

json

{
  "_tag": "v1",
  "value": {
    "tallesx": {
      "status": "AVAILABLE",
      "availableDigits": [
        1,
        2,
        3
      ]
    },
    "takenx": {
      "status": "EXHAUSTED"
    },
    "abc": {
      "status": "INVALID"
    }
  }
}

Response · 400 · application/json

json

{
  "error": "The request body contains invalid values.",
  "fields": [
    {
      "field": "usernames",
      "message": "must contain at most 100 items"
    }
  ]
}

Response · 500 · application/json

json

{
  "error": "Internal server error. Please try again."
}

200 OK

Per-base availability read from People Chain UsernameOwnerOf plus pending outbox reservations, tagged {_tag: "v1", value} with availableDigits. EXHAUSTED means nothing claimable under this base: no free discriminator, or the bare personhood name is owned or its reservation queue is full — the last two would make a claim carrying dotns.reservedUsername fail on chain and take the lite username with it.

400 The request body contains invalid values.

Invalid usernames, or malformed JSON.

401 UNAUTHORIZED

Missing or invalid bearer token.

429 RATE_LIMITED

Subject rate limit exceeded (with Retry-After).

500 Internal server error. Please try again.

People Chain failure or reservation-outbox failure.

GET /api/v1/usernames/search?prefix=<prefix>&limit=<limit>&cursor=<cursor>

200 400 402 429 public

Public prefix search over the finalized username projection.

Header	Type	Required	Description
Authorization	string	no	Optional `Bearer <JWT>` from device-attestation. When proof of compute is enabled, a valid token satisfies this route and no puzzle is needed. An unverifiable token is treated as anonymous — this route never answers 401.
Proof-Of-Compute	string	no	Solved puzzle, required only when proof of compute is enabled and no valid bearer token is presented: `base64(sessionId:timestamp:difficulty:counter:checksum)` for a puzzle from `POST /api/v1/poc/issue`. Single-use.

Query	Type	Required	Description
prefix	string	yes	Prefix of letters/digits, optionally followed by a dot and digits.
limit	number	no	Requested page size, defaulting to 100 and clamped to 1,000.
cursor	string	no	Opaque continuation cursor from an earlier response.

Response · 200 · application/json

json

{
  "usernames": [],
  "nextCursor": null
}

Response · 400 · application/json

json

{
  "error": "The request query contains invalid values.",
  "fields": [
    {
      "field": "prefix",
      "message": "Prefix is required"
    }
  ]
}

Response · 402 · application/json

json

{
  "error": "Proof of compute required. Request a puzzle from POST /api/v1/poc/issue and present the solved proof in the Proof-Of-Compute header."
}

Response · 429 · application/json

json

{
  "error": "Rate limit exceeded. Please retry after 60 seconds."
}

200 OK

Matching assigned usernames in continuation order. Registrations whose on-chain identifier key predates chat-spec RFC-0004 (pre-X25519) are omitted — the app cannot message them.

400 The request query contains invalid values.

Invalid query parameter (with per-field fields), invalid cursor ({"error":"Invalid cursor"}), or a malformed Proof-Of-Compute header.

402 Proof of compute required. Request a puzzle from POST /api/v1/poc/issue and present the solved proof in the Proof-Of-Compute header.

Proof of compute is enabled and the caller presented neither a valid bearer token nor an acceptable puzzle. The error names the reason: missing proof, checksum mismatch, expired puzzle, already-used puzzle, or insufficient difficulty.

429 Rate limit exceeded. Please retry after 60 seconds.

Public rate limit exceeded (with Retry-After).

06

Proof of compute

#

POST /api/v1/poc/issue

201 404 public

Issue a proof-of-compute puzzle for an unauthenticated caller.

Response · 201 · application/json

json

{
  "sessionId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "timestamp": 1700000000000,
  "difficulty": 16,
  "checksum": "c8828951fd6c123fdbf6501f111d27dd3f260839344a7370e0dd8f20e2c40482"
}

Response · 404 · application/json

json

{
  "error": "Not found"
}

201 CREATED

A fresh puzzle to solve. Mine a counter whose sha256(sessionId || timestamp || counter) has at least difficulty leading zero bits, then send Proof-Of-Compute: base64(sessionId:timestamp:difficulty:counter:checksum) on the search request. Callers holding an device-attestation JWT do not need a puzzle.

404 Not found

Proof of compute is disabled on this deployment (POC_ENABLED=false): the route is not mounted and the service-wide 404 answers instead.

07

Invitation Tickets

#

POST /api/v1/invitation-ticket/claim

200 400 401 409 422 429 500 bearer JWT

Claim an invitation ticket for a DIM, returning a signature (JWT-gated).

Auth Bearer JWT required in the Authorization header.

Field	Type	Required	Description
who	string	yes	SS58 address to claim a ticket for (any valid SS58 prefix).
dim	string	yes	DIM to claim a ticket for: `Game` or `ProofOfInk`.

Request Body

json

{
  "who": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty",
  "dim": "Game"
}

Response · 200 · application/json

json

{
  "publicKey": "0xda8ab326da384dd49d5f12543b58acae730af7388b9348c51af6ee3a0962864d",
  "inviter": "5C4hrfjw9DjXZTzV3MwzrrAr9P1MJhSrvWGWqi1eSuyUpnhM",
  "dim": "Game",
  "network": "paseo",
  "claimedBy": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty",
  "createdAt": "2026-07-01T10:20:30.400Z",
  "claimedAt": "2026-07-02T11:00:00.000Z",
  "signature": "0xa4a506e96aff250724590ef9527d8117ea2e9d633e813d22d32ad17e0b5c253c406cb22baf62283c6987f81b9bb55ea75f3bdff0259d84e5c282728043f77c88",
  "remaining": 41
}

200 OK

Ticket claimed: the oldest available ticket of the (dim, network) pool, atomically flipped to claimed, with an sr25519 signature by the ticket key over the claimant's decoded 32-byte account id.

400 WRONG_DATA

Body validation failed (with per-field fields), or Malformed JSON in request body when the body is not JSON.

401 UNAUTHORIZED

Missing/malformed Authorization header or failed token verification.

409 CONFLICT

Ticket race lost — a concurrent request claimed the contended ticket.

422 422

Pool exhausted — no available ticket in the (dim, network) pool.

429 RATE_LIMITED

Per-subject rate limit exceeded (with Retry-After).

500 INTERNAL

Unexpected internal failure (opaque).

08

TURN

#

POST /api/v1/turn/issue

201 400 401 429 503 bearer JWT

Issue short-lived TURN credentials for WebRTC ICE negotiation (JWT-gated).

Auth Bearer JWT required in the Authorization header.

Field	Type	Required	Description
regionHint	string	no	Optional region hint (reserved for future use; accepted and ignored).

Request Body

json

{
  "regionHint": "eu-west"
}

Response · 201 · application/json

json

{
  "servers": [
    "stun:stun.cloudflare.com:3478",
    "turn:turn.cloudflare.com:3478?transport=udp",
    "turn:turn.cloudflare.com:3478?transport=tcp",
    "turns:turn.cloudflare.com:5349?transport=tcp"
  ],
  "username": "d2f4a1c6b8e05379",
  "password": "9f83b1e6c0a74d25b3f8e1a70c4d69b2",
  "ttl": 1800
}

201 CREATED

Credentials issued: username and password are an opaque pair from the deployment's configured TURN_PROVIDER — do not parse either — servers is the ICE server list to use them against, and ttl is the seconds of life remaining on the credential.

400 WRONG_DATA

Body validation failed (with per-field fields), or Malformed JSON in request body when a body is present but not JSON. An empty body is accepted — every field is optional.

401 UNAUTHORIZED

Missing/malformed Authorization header or failed token verification.

429 RATE_LIMITED

Per-subject rate limit exceeded (with Retry-After).

503 UNAVAILABLE

The credential provider could not issue and no cached credential was usable (with Retry-After). Only reachable on the Cloudflare provider, which depends on an upstream call; a coturn deployment computes credentials locally and never returns this.

POST /api/v1/turn/issue-with-proof

201 400 403 429 503 public

Redeem a personhood proof for the same credentials as /turn/issue.

Field	Type	Required	Description
productId	string	yes	The product the proof was made for. Its context is the one the proof is verified under, so a product proves under its own identifier. Must be one this deployment accepts.
collection	string	yes	Hex-encoded 32-byte collection id from the proof's TrUAPI `ringLocation`. Only the canonical People Lite and People collections are accepted.
proof	string	yes	Ring-VRF proof over the derived message (hex), exactly as the host returns it — raw signature bytes, with no SCALE length prefix.
ringIndex	number	yes	Ring containing the proving member, used to locate the root.
ringRevision	number	yes	Revision of that ring the proof was made against, as the host reports it. Only that revision's root is tried, so a revision this deployment no longer holds is refused without verifying anything.
timestamp	number	yes	Client Unix seconds, bound into the proved message. Must be within the server's accepted skew.

Request Body

json

{
  "productId": "vox.dot",
  "collection": "0x706f703a706f6c6b61646f742e6e6574776f726b2f70656f706c652d6c697465",
  "proof": null,
  "ringIndex": 0,
  "ringRevision": 3,
  "timestamp": 1784757652
}

Response · 201 · application/json

json

{
  "servers": [
    "stun:stun.cloudflare.com:3478",
    "turn:turn.cloudflare.com:3478?transport=udp",
    "turn:turn.cloudflare.com:3478?transport=tcp",
    "turns:turn.cloudflare.com:5349?transport=tcp"
  ],
  "username": "d2f4a1c6b8e05379",
  "password": "9f83b1e6c0a74d25b3f8e1a70c4d69b2",
  "ttl": 1800
}

201 CREATED

Proof accepted; returns the servers and an opaque username/password pair from the configured TURN_PROVIDER, and ttl, the seconds of life remaining on them. No alias appears in the response, and nothing recoverable from the proof is derivable from the credential.

400 WRONG_DATA

Unparseable body, invalid hex, a collection outside the canonical People Lite/People allowlist, a proof that is not a single-context ring-VRF signature, a product this deployment does not accept, or a timestamp outside the accepted skew.

403 FORBIDDEN

The proof did not verify against the named ring root under that product's context — including when (ringIndex, ringRevision) is outside the roots this deployment still holds (deliberately unspecific).

429 RATE_LIMITED

This person's redemption limit was exceeded (with Retry-After).

503 UNAVAILABLE

Verification unavailable: no ring-root snapshot yet (chain unreachable since boot), the bounded waiter queue is full, or all verification slots remained busy for the bounded wait. Also returned when the proof verified but the credential provider could not issue and no cached credential was usable, which only the Cloudflare provider can do. Saturation and provider responses include Retry-After.

09

Notifications

#

POST /api/v1/notify

200 400 401 429 bearer JWT

Order mirrors the sibling services: verified JWT (401 problem details) → body parse (400 plain text on malformed JSON) → body validation (400 problem details with per-field errors) → per-subject rate limit (429 with Retry-After). Beyond that the relay always answers 200: on provider failure it preserves the legacy success: false body instead of an error status.

Auth Bearer JWT required in the Authorization header.

Field	Type	Required	Description
deviceToken	string	yes	Recipient device token (APNs hex or FCM token); platform is auto-detected.
pushId	string	yes	Opaque push id echoed to the client app (32 or 64 hex chars).
message	string	yes	Hex-encoded, already-encrypted message body (optional `0x` prefix).
platform	string	no	Explicit platform override; auto-detected from the token when omitted.
bundlerId	string	no	APNs topic override (the app bundle id); VoIP derives `<topic>.voip`.
voip	boolean	no	Enable the iOS VoIP push type for a call.

Request Body

json

{
  "deviceToken": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "pushId": "5d41402abc4b2a76b9719d911017c592",
  "message": "0x1234567890abcdef",
  "platform": "ios",
  "bundlerId": "io.parity.brevity",
  "voip": false
}

Response · 200 · application/json

json

{
  "success": true,
  "platform": "ios",
  "sent": 1,
  "failed": 0,
  "messageId": null,
  "errors": null
}

200 OK

Relay accepted the request. The push result is echoed verbatim from the provider — including the legacy behavior of returning 200 with success: false on provider failure, so a non-200 status never signals a delivery failure.

400 WRONG_DATA

Body validation failed (RFC 9457 problem details with per-field errors); or plain-text Malformed JSON in request body when the body is not JSON.

401 UNAUTHORIZED

Missing/malformed Authorization header or failed token verification (RFC 9457 problem details).

429 RATE_LIMITED

Per-subject rate limit exceeded (RFC 9457 problem details, with Retry-After).

06

Error Model

#

All non-2xx responses share a single envelope. error is a stable machine code; message is a human-readable detail that may vary.

Error JSON Shape

json

{
  "error": "WRONG_DATA",
  "message": "human-readable detail"
}

400 WRONG_DATA

Malformed body/header, invalid username, empty search prefix.

401 UNAUTHORIZED

Missing/invalid bearer token, bad challenge, bad proof, spent refresh token.

403 FORBIDDEN

candidateAccountId does not match JWT subject.

409 CONFLICT

Preferred digits or username already taken/reserved.

429 RATE_LIMITED

Per-route rate limiter exceeded.

500 INTERNAL

Unexpected backend/database/chain failure.

07

Smoke Commands

#

Bare-bones curl sequence that exercises the public surface of the service. Safe to run from any shell.

smoke.sh

BASE="https://identity.dotspark.app"

curl -fsS "$BASE/healthcheck"
curl -fsS "$BASE/readyz"
curl -fsS -X POST "$BASE/api/v1/auth/challenges"
curl -fsS "$BASE/api/v1/attester"
curl -fsS "$BASE/.well-known/jwks.json"

Full token and username calls require the mobile app or a client that can produce the sr25519 proof headers. The bundled repo example can drive the flow against a base URL.

Device Uniqueness Backend v2

Validation Flow

Liveness & Readiness

Discovery

Authentication

Usernames

Proof of compute

Invitation Tickets

TURN

Notifications

Error Model

Smoke Commands