# Protect sign-ups with ShieldShiba

> A free captcha that checks the email address and the browser.

ShieldShiba sits next to the email field on a sign-up or contact form. When a visitor types an address, the widget runs a short proof-of-work in the browser and checks the email, the IP, and the browser. There is no puzzle. A visitor who looks automated waits a few seconds longer while their browser does more work. A visitor who passes sees **Verified** and the form gets a token. Your server sends that token to PostShiba before it accepts the sign-up.

The token is bound to the email the visitor typed, so a solved check cannot be reused for a different address. Blocked visitors never see the reason. When the block came from their IP, usually a VPN or proxy, the widget asks them to turn off the VPN and try again. When you block free email, it asks them to use their business email address. Only your server and the ShieldShiba page see the reasons.

PostShiba stores the email's domain and a keyed SHA-256 digest (HMAC) of the address, never the address itself. It also keeps the IP, the user agent, and the verdict.

## Before you start

- A PostShiba account. Open **Security**, then **ShieldShiba**.
- The hostnames that will embed the widget.

## 1. Create a site

On **ShieldShiba**, choose **Add site**. List the hostnames under **Allowed hostnames**. Subdomains of a listed hostname are allowed.

Each site has two keys.

- The **Site key** starts with `ss_pk_`. It is public and goes in your HTML.
- The **Secret key** starts with `ss_sk_`. Keep it on your server. Use **Rotate secret** on the same page if it leaks. The old secret stops working at once.

Four settings are per site.

- **Block hosting networks** is on by default. Turn it off to allow data-center and hosting IPs.
- **Block free email** is off by default. Turn it on if sign-ups should use a work address.
- **Camera check instead of a block** is off by default. See [Ask for a camera check](#ask-for-a-camera-check).
- **Ask for a camera check** is off by default. See [Ask for a camera check](#ask-for-a-camera-check).

## 2. Embed the widget

Load the script once, then put a `<shield-shiba>` tag inside the form. Point `email-field` at the email input with a CSS selector.

```html signup.html
<script src="https://postshiba.com/shield/v1/widget.js" async></script>

<form action="/signup" method="post">
  <input type="email" name="email" id="email">
  <shield-shiba sitekey="ss_pk_..." email-field="#email"></shield-shiba>
  <button>Sign up</button>
</form>
```

When the visitor passes, the widget adds a hidden input named `shield_shiba_token` to the form. A blocked visitor gets no token.

The widget also adds one text field that no visitor can see or reach. The field has no name, so the browser never posts it with your form. Only a script that fills every input writes in it. Leave it empty in your own scripts and tests.

## 3. Verify the token

Send the token, the email from the submitted form, and your secret key to the verify endpoint. No API key. The email must match the address the visitor typed.

```bash verify.sh
curl -sS \
  --request POST \
  --url "https://app.postshiba.com/shield/v1/verify" \
  --header "Content-Type: application/json" \
  --data '{
    "secret": "ss_sk_...",
    "token": "TOKEN_FROM_FORM",
    "email": "you@example.com"
  }'
```

A valid token returns `200`.

```json verify-response.json
{
  "success": true,
  "verdict": "good_boy",
  "reasons": [],
  "email": "you@example.com",
  "hostname": "example.com",
  "created_at": "2026-09-23T05:12:44Z"
}
```

Accept the sign-up only when `success` is `true` and `verdict` is `good_boy`. Blocked visitors never get a token, so a successful verify always returns `good_boy`. `hostname` is the page the widget ran on. `email` is normalized. A visitor who passed the camera check returns `reasons: ["liveness"]`. A visitor who passed after extra work returns the [signs of automation](#signs-of-automation) that caused it, such as `reasons: ["robotic_typing"]`.

Each token is single-use and valid for 5 minutes. Just before a token expires, the widget clears it and asks the visitor to verify again.

| Status | Body | Meaning |
| --- | --- | --- |
| `401` | `{"success": false, "error": "invalid_secret"}` | The secret key does not belong to the token's site. |
| `422` | `{"success": false, "error": "invalid_token"}` | The token is missing, unknown, already used, expired, or bound to a different email. |

Treat any error as a failed check. Ask the visitor to try again. The account labels these verdicts **Passed** and **Blocked**.

## Reasons

Some checks block on their own. The inspector stops at the first one that fails. That reason is stored on the blocked row in the account.

| Reason | Meaning |
| --- | --- |
| `invalid_email` | The address is not well formed. |
| `no_mx` | The domain has no mail server. |
| `temp_email` | The domain is a disposable or temporary inbox. |
| `sfs_domain` | The domain is on the StopForumSpam blocklist. |
| `free_email` | The domain is free webmail. Only when **Block free email** is on. |
| `network_bounced` | The address hard-bounced or was reported as spam with more than one PostShiba sender. |
| `machine_agent` | The browser is scripted. Headless tools, curl, webdriver, or a form filled in under 300 ms. |
| `sfs_ip` | The IP is on the StopForumSpam blocklist. |
| `abuseipdb_listed` | The IP has an AbuseIPDB confidence score of 50 or higher. |
| `tor` | The IP is a Tor exit node. |
| `hosting_ip` | The IP belongs to a data center or hosting network. Only when **Block hosting networks** is on. |
| `not_live` | The camera check did not show one live person doing the poses, or it reused stills from another check. Only when a camera check is on. |
| `suspicious` | Several signs of automation at once. The signs follow it in the list. See [Signs of automation](#signs-of-automation). |

Do not show these strings to the visitor. For `sfs_ip`, `abuseipdb_listed`, `tor`, and `hosting_ip`, the widget already tells the visitor to turn off their VPN and try again. For `free_email`, it asks them to use their business email address.

## Signs of automation

Other checks are evidence, not proof. An office behind one IP looks like a bot farm, and a password manager types like a script. So no sign that a real browser can show blocks a visitor on its own, apart from `recently_reported_ip`.

Each sign adds to a score. Signs with one likely cause count once. A changed user agent gives both `ua_mismatch` and `platform_mismatch`, and the other network signs can never block without a sign from the browser. A visitor with a low score passes as before. A visitor with a higher score gets a harder proof-of-work instead of a token. Their widget shows **Extra check**, solves it in a few seconds, and then passes. Their token's `reasons` list the signs. A visitor with a high score is blocked with the reason `suspicious` and told to try another browser or network, or gets the camera check when **Camera check instead of a block** is on.

| Reason | Meaning |
| --- | --- |
| `no_accept_language` | The request named no language. Every browser names one. |
| `odd_fetch_metadata` | The browser's own description of the request does not fit a request from the widget. |
| `platform_mismatch` | The operating system in the user agent is not the one the browser reports elsewhere. |
| `ua_mismatch` | The page, its background worker, and the request name different browsers. |
| `ip_changed` | The proof-of-work was solved from a different IP than the one that asked for it. |
| `noisy_network`, `very_noisy_network` | ShieldShiba blocked bots from 3 or more, or 10 or more, addresses on the same network in the last 24 hours, on any site. |
| `reported_ip`, `often_reported_ip` | The IP has an AbuseIPDB confidence score of 10 or higher, or 25 or higher, and below the 50 that blocks. The visitor gets the hardest proof-of-work, and one sign from the browser blocks them. |
| `recently_reported_ip` | In the last 14 days the IP was reported to AbuseIPDB, and over 90 days at least 3 reporters named at least 2 kinds of abuse. This sign alone is a high score, whatever the confidence score. The widget tells the visitor to turn off their VPN and try again. |
| `many_emails`, `very_many_emails` | The same IP checked more than 5, or more than 20, different emails on this site in an hour. |
| `no_signals` | The client reported nothing about the browser. The widget always does, so this sign alone is a high score. |
| `no_render` | The browser did not lay out the widget, as a script without a screen does not. |
| `no_interaction` | No click, tap, or key press reached the page before the check. |
| `no_languages` | The browser lists no languages. |
| `robotic_typing` | The email was typed faster or more evenly than a person types. |
| `honeypot` | Something wrote in the hidden field. |
| `automation` | An automation tool left its traces on the page. |

ShieldShiba also starts a visitor on a harder proof-of-work when the request or the network already shows one of these signs. The widget reports counts and timings only. It never reads which keys the visitor pressed or where the pointer was.

Your own browser tests look automated too. Add the IP of your test runner to the [allowlist](#let-a-trusted-visitor-through).

## Ask for a camera check

Turn on **Ask for a camera check** to stop AI agents and scripted sign-ups that pass the other checks. It is off by default and set per site.

Turn on **Camera check instead of a block** to ask only the visitors with a high automation score. Everyone else never sees the camera. A person whom the score got wrong can then prove it, where they would otherwise be blocked as `suspicious`.

After the email passes, the widget asks the visitor to turn on their camera. It shows five quick poses in a random order, like turn left, raise your eyebrows, or smile, and takes one still for each. AI checks that the stills show one live person in front of the camera doing those poses, not a photo, a screen, or a generated face. Then the form gets its token.

The stills are checked once and never stored. PostShiba sends them to its AI provider with storage turned off and keeps only a short fingerprint of each for a week, so the same stills can't pass twice. A fingerprint can't be turned back into a picture. No video is recorded.

A visitor without a camera, or who won't turn it on, can't pass. Only turn it on where that is acceptable. Allowlisted visitors skip the camera check like every other check.

## Let a trusted visitor through

Some real people can't turn off their VPN, like a traveller on a mobile eSIM. Add them to the site's **Allowlist** on the ShieldShiba page. An entry is an IP, an IP range such as `198.51.100.0/24`, an email domain, or a full email address. A domain also covers its subdomains. A visitor who matches any entry skips every check and passes with the reason `allowlisted`.

On a blocked row under **Latest checks**, **Allow IP** and **Allow domain** add that row's IP or domain in one click. Mobile carriers change IPs often, so for an eSIM user, allow their email address or domain instead of the IP.

## Check the token in Rails

Read the token from the form params and call verify before you create the user.

```ruby app/controllers/registrations_controller.rb
require "net/http"

class RegistrationsController < ApplicationController
  SHIELD_VERIFY_URL = URI("https://app.postshiba.com/shield/v1/verify")

  def create
    email = params.require(:email)
    unless shield_passed?(email, params[:shield_shiba_token])
      flash.now[:alert] = "Please try again."
      return render :new, status: :unprocessable_entity
    end

    User.create!(email: email)
    redirect_to root_path
  end

  private

  def shield_passed?(email, token)
    return false if token.blank?

    response = Net::HTTP.post(
      SHIELD_VERIFY_URL,
      {secret: ENV.fetch("SHIELD_SHIBA_SECRET"), token: token, email: email}.to_json,
      "Content-Type" => "application/json"
    )
    body = JSON.parse(response.body)
    response.is_a?(Net::HTTPOK) && body["success"] && body["verdict"] == "good_boy"
  rescue JSON::ParserError, Net::OpenTimeout, Net::ReadTimeout
    false
  end
end
```

Log `reasons` on a failure if you want to see why a sign-up was blocked.

If you send a welcome email after `User.create!`, use a Send only key from [Create an API key](/docs/create-an-api-key). The verify call itself needs no API key.

## Next steps

- [ShieldShiba](/docs/api-reference/shield)
- [How to set the email firewall](/docs/dashboard/emails/email-firewall)
- [How to manage suppressions](/docs/dashboard/emails/email-suppressions)
