HumanProof

Verify a HumanProof token

post /humanproof/verify

Check a HumanProof token on your server before you accept the form or action it came with. Each token can be checked once. Call it from your server, never from the browser: the browser can send anything.

Authentication

None. This endpoint takes no token.

Body application/json

origin string required

The host of the page the person used, exactly as you registered it under HumanProof → Sites.
token string required

The humanproof-token the widget added to your form, or the token your page received from the widget.

Responses

200 The token was checked. Act on valid: a refused token is still a 200.
Show response fields
- valid boolean required
  
  Whether to accept the request. The only field you need to act on.
- tier string
  
  How presence was shown. Present when valid is true.
  
  One of prove , prove_plus , attested
- code string
  
  Why the token was refused. Present when valid is false. Log it; don't show it to the person.
  
  One of spent , origin_not_enabled , below_site_policy , invalid , malformed , bad_request , error
400 The body was not JSON, or origin or token was missing.
404 HumanProof is not turned on for this issuer.
500 The check could not be made. Treat it as not verified and let the person try again.

Errors

A refused token comes back with a code to branch on. What each means and what to do:

Status	Code	What to do
200	spent	The token was already checked once. Ask the person to prove presence again.
200	origin_not_enabled	The origin is not a site registered for HumanProof. Check it matches the host under HumanProof → Sites exactly.
200	below_site_policy	Presence was shown, but not as strongly as this site's policy requires.
200	invalid	The token is not one HumanProof issued.
200	malformed	The token is not valid base64url.
400	bad_request	Send a JSON body with both `origin` and `token`.

Request

curl -X POST "https://id.trustaige.com/humanproof/verify" \
  -H "Content-Type: application/json" \
  -d '{"origin":"www.example.com","token":"<humanproof-token>"}'

const res = await fetch('https://id.trustaige.com/humanproof/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "origin": "www.example.com",
    "token": "<humanproof-token>"
  }),
});
const data = await res.json();

body := strings.NewReader(`{
  "origin": "www.example.com",
  "token": "<humanproof-token>"
}`)
req, err := http.NewRequest(http.MethodPost, "https://id.trustaige.com/humanproof/verify", body)
if err != nil {
    return err
}
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close()

import requests

res = requests.post(
    "https://id.trustaige.com/humanproof/verify",
    json={
        "origin": "www.example.com",
        "token": "<humanproof-token>"
    },
    timeout=10,
)
data = res.json()

Responses

{
  "valid": true,
  "tier": "prove"
}

{
  "valid": false,
  "code": "bad_request"
}

{
  "valid": false,
  "code": "error"
}