Sign in to fill these examples with your own keys. Sign in Start free trial

ShieldShiba

Bot checks for signup and contact forms.

Bot checks for your signup and contact forms. Each site has a public site key for the widget and a secret key for your server. secret_key is returned on create and rotate_secret, and on show to Admins, not on index or update. allowed_hostnames also takes a comma or space separated string. Subdomains of an allowed hostname pass. block_hosting blocks traffic from hosting and datacenter networks. block_free_email blocks free mailbox providers. require_liveness asks visitors who pass for a camera check: they follow a few random poses and AI confirms a live person, and verify returns reasons ["liveness"]. Visitors without a camera cannot pass it. liveness_on_suspicion asks only visitors who look automated for that camera check, instead of blocking them. allowlist holds IPs, CIDR ranges, email domains, and email addresses that skip every check; it takes an array or a comma, space, or newline separated string, and an update replaces the whole list. A visitor who matches passes with reasons ["allowlisted"]. A visitor can also pass with soft reasons such as ["noisy_network"]: signs of automation that were not enough to block, and that made their browser do more work first. verifications_7d counts passed and blocked checks over the last 7 days. Redeem a widget token from your server with POST /shield/v1/verify.

GET /api/v1/teams/:obfuscated_team_id/shield_sites

List sites. secret_key is omitted.

request.sh
1curl -sS -X GET \ 2 -H 'Authorization: Bearer YOUR_API_KEY' \ 3 https://app.postshiba.com/api/v1/teams/KjkAJW/shield_sites
response.json
1[ 2 { 3 "id": "ShLdSt", 4 "name": "Signup", 5 "public_key": "ss_pk_7Fm2Qx9Lt4Wd8Nc1Hv6Bs3Kz", 6 "allowed_hostnames": [ 7 "acme.com", 8 "app.acme.com" 9 ], 10 "block_hosting": true, 11 "block_free_email": false, 12 "require_liveness": false, 13 "liveness_on_suspicion": false, 14 "allowlist": [ 15 "203.0.113.7", 16 "partner.example" 17 ], 18 "verifications_7d": { 19 "passed": 128, 20 "blocked": 9 21 }, 22 "created_at": "2026-09-23T00:00:00Z" 23 } 24]

GET /api/v1/shield_sites/:id

Get one site. Admins also get the secret key.

  • id: Public site id
request.sh
1curl -sS -X GET \ 2 -H 'Authorization: Bearer YOUR_API_KEY' \ 3 https://app.postshiba.com/api/v1/shield_sites/:shield_site_id
response.json
1{ 2 "id": "ShLdSt", 3 "name": "Signup", 4 "public_key": "ss_pk_7Fm2Qx9Lt4Wd8Nc1Hv6Bs3Kz", 5 "allowed_hostnames": [ 6 "acme.com", 7 "app.acme.com" 8 ], 9 "block_hosting": true, 10 "block_free_email": false, 11 "require_liveness": false, 12 "liveness_on_suspicion": false, 13 "allowlist": [ 14 "203.0.113.7", 15 "partner.example" 16 ], 17 "verifications_7d": { 18 "passed": 128, 19 "blocked": 9 20 }, 21 "created_at": "2026-09-23T00:00:00Z", 22 "secret_key": "ss_sk_2w9Qh4Lk8Xz1Vn6Rb3Tm7Pc5" 23}

POST /api/v1/teams/:obfuscated_team_id/shield_sites

Create a site. Returns the public and secret keys.

request.sh
1curl -sS -X POST \ 2 -H 'Authorization: Bearer YOUR_API_KEY' \ 3 -H 'Content-Type: application/json' \ 4 -d '{"shield_site":{"name":"Signup","allowed_hostnames":"acme.com, app.acme.com","block_hosting":true,"block_free_email":false}}' \ 5 https://app.postshiba.com/api/v1/teams/KjkAJW/shield_sites
response.json
1{ 2 "id": "ShLdSt", 3 "name": "Signup", 4 "public_key": "ss_pk_7Fm2Qx9Lt4Wd8Nc1Hv6Bs3Kz", 5 "allowed_hostnames": [ 6 "acme.com", 7 "app.acme.com" 8 ], 9 "block_hosting": true, 10 "block_free_email": false, 11 "require_liveness": false, 12 "liveness_on_suspicion": false, 13 "allowlist": [ 14 "203.0.113.7", 15 "partner.example" 16 ], 17 "verifications_7d": { 18 "passed": 128, 19 "blocked": 9 20 }, 21 "created_at": "2026-09-23T00:00:00Z", 22 "secret_key": "ss_sk_2w9Qh4Lk8Xz1Vn6Rb3Tm7Pc5" 23}

PATCH /api/v1/shield_sites/:id

Update name, allowed_hostnames, block_hosting, block_free_email, require_liveness, liveness_on_suspicion, or allowlist. secret_key is omitted.

  • id: Public site id
request.sh
1curl -sS -X PATCH \ 2 -H 'Authorization: Bearer YOUR_API_KEY' \ 3 -H 'Content-Type: application/json' \ 4 -d '{"shield_site":{"block_free_email":true}}' \ 5 https://app.postshiba.com/api/v1/shield_sites/:shield_site_id
response.json
1{ 2 "id": "ShLdSt", 3 "name": "Signup", 4 "public_key": "ss_pk_7Fm2Qx9Lt4Wd8Nc1Hv6Bs3Kz", 5 "allowed_hostnames": [ 6 "acme.com", 7 "app.acme.com" 8 ], 9 "block_hosting": true, 10 "block_free_email": true, 11 "require_liveness": false, 12 "liveness_on_suspicion": false, 13 "allowlist": [ 14 "203.0.113.7", 15 "partner.example" 16 ], 17 "verifications_7d": { 18 "passed": 128, 19 "blocked": 9 20 }, 21 "created_at": "2026-09-23T00:00:00Z" 22}

POST /api/v1/shield_sites/:id/rotate_secret

Issue a new secret key. The old one stops working at once. The site key is unchanged.

  • id: Public site id
request.sh
1curl -sS -X POST \ 2 -H 'Authorization: Bearer YOUR_API_KEY' \ 3 -H 'Content-Type: application/json' \ 4 https://app.postshiba.com/api/v1/shield_sites/:shield_site_id/rotate_secret
response.json
1{ 2 "id": "ShLdSt", 3 "name": "Signup", 4 "public_key": "ss_pk_7Fm2Qx9Lt4Wd8Nc1Hv6Bs3Kz", 5 "allowed_hostnames": [ 6 "acme.com", 7 "app.acme.com" 8 ], 9 "block_hosting": true, 10 "block_free_email": false, 11 "require_liveness": false, 12 "liveness_on_suspicion": false, 13 "allowlist": [ 14 "203.0.113.7", 15 "partner.example" 16 ], 17 "verifications_7d": { 18 "passed": 128, 19 "blocked": 9 20 }, 21 "created_at": "2026-09-23T00:00:00Z", 22 "secret_key": "ss_sk_8Jd3Ns5Wq1Yf7Kt2Gx9Hr4Lb" 23}

DELETE /api/v1/shield_sites/:id

Delete a site. Widgets using its site key stop passing.

  • id: Public site id
request.sh
1curl -sS -X DELETE \ 2 -H 'Authorization: Bearer YOUR_API_KEY' \ 3 https://app.postshiba.com/api/v1/shield_sites/:shield_site_id

POST https://app.postshiba.com/shield/v1/verify

Redeem a widget token from your server. No API key. Send the site's secret key, the token, and optionally the email the visitor typed. A token redeems once and expires after 5 minutes. 401 invalid_secret. 422 invalid_token.

request.sh
1curl -sS -X POST \ 2 -H 'Content-Type: application/json' \ 3 -d '{"secret":"ss_sk_2w9Qh4Lk8Xz1Vn6Rb3Tm7Pc5","token":"widget-token","email":"jane@acme.com"}' \ 4 https://app.postshiba.com/shield/v1/verify
response.json
1{ 2 "success": true, 3 "verdict": "good_boy", 4 "reasons": [], 5 "email": "jane@acme.com", 6 "hostname": "acme.com", 7 "created_at": "2026-09-23T00:00:00Z" 8}