Reference

Appeals

When Nolgard gets a real person wrong, they can ask you to review the decision.

Browser call

// On a block, challenge or limit, after you show the reference:
const result = await Nolgard.appeal({ ref });
// result.status is 'submitted' or 'duplicate'

Option	Type	Notes
ref	string	Required. The `ev_…` reference returned by verify.
message	string	Optional. Prefills the message box. The user can edit it; up to 500 characters.

The modal shows the reference, runs a step-up check for that same ref, takes an optional message and submits one review request. It rejects if the user cancels, so handle the rejection. If the step-up challenge is cancelled or unavailable, the appeal is still submitted, without that proof.

Endpoint

POST https://nolgard.com/v1/appeal
{"siteKey":"pk_…","ref":"ev_…","stepUpToken":"…","message":"I was setting up my own account."}

{"status":"submitted"}

Field	Type	Notes
siteKey	string	Required. Public site key. Sent by the browser SDK.
ref	string	Required. The event reference.
stepUpToken	string	Optional. Proof that the step-up for this ref passed.
message	string	Optional. Up to 500 characters.

Field	Type	Notes
status	string	`submitted` for a new appeal, `duplicate` when this event already has one.

One appeal per event.

Errors

Status	Error	Notes
400	invalid-input	Missing or oversized fields.
403	origin-not-allowed	The call must come from one of the site's allowed origins.
404	unknown-site	No site for that key.
409	not-appealable	One indistinguishable answer for an unknown, foreign, allowed or shadowed event. Shadowed users are never told.
429	rate-limited	More than 20 appeals an hour from one IP.

Review

The owner reviews appeals in the dashboard → Appeals, split into open and resolved. Approve applies the same legit label as feedback; reject applies fraud. See Test keys and feedback for what labels do.

Webhooks

appeal.opened
{"ref":"ev_…","accountId":"user_42","decision":"block","stepUpPassed":true}

appeal.resolved
{"ref":"ev_…","accountId":"user_42","outcome":"approve"}

outcome is approve or reject. On approve, restore access or credits in your backend: Nolgard relabels the event, it does not undo what your application did. See Webhooks and clawback.

Data retention

Appeal messages are deleted after 30 days. Resolved appeals are deleted after 90 days.

Limits

Appeals are interactive only. They need a browser and the reference your application displayed.
Allowed and shadowed events are never appealable, and the answer is the same as for an unknown reference.
A passed step-up is evidence rather than proof of identity. An appeal without one is still reviewable.
One appeal per event; a second call returns duplicate rather than opening a new review.
Review is manual. Nothing is restored until an owner resolves the appeal and your backend acts on the webhook.
The rate limit is per IP, so users behind one NAT share it.