Docs: set up osec.one tools in minutes
Get started
- Click Login / Sign up and sign in with an email code, Google or Apple.
- The console opens. Add a project (for sign-in) or a site key (for captcha, CSP reports, checks, bot gate).
- Copy the snippet for your stack and paste it into your site.
- Watch usage under Usage & billing. Free: 500 requests a day.
osec Auth (passwordless sign-in)
- Console → Projects → Add project. Enter your site's domain.
- Open Auth config → pick email code, Google and/or Apple.
- Paste the widget, using your project's appcode.
- Open the dialog from any button. Listen for the login event.
- On your API, validate the session token before trusting a request.
html
<script>
window.OSEC_ONE_AUTH_CONFIG = { appcode: "YOUR_APPCODE" };
</script>
<script src="https://osec.one/assets/osec-auth/osec_one_auth.js"></script>
<button onclick="window.osec_one_auth.open()">Sign in</button>
<script>
window.addEventListener("osec_one:login:success", (e) => {
console.log("signed in as", e.detail.email); // session cookie is set
});
</script>bash: validate a session on your server
curl -X POST https://api2.osec.one/validate \
-H "appcode: YOUR_APPCODE" \
--cookie "session=TOKEN_FROM_THE_BROWSER"
# 200 {"user_uuid": "...", "user_email": "..."} or 401- Templates for React, React Native, WordPress, Wix and Squarespace are in the console (Auth config → Code blocks).
- Google and Apple consent screens show "osec.one" as the app name.
osec Captcha
Invisible proof-of-work: the browser solves a small puzzle, people see a check mark. A drop-in for reCAPTCHA's siteverify.
- Console → Site keys → New key (list your hostnames). Copy the secret.
- Add the widget inside your form and load the script.
- On submit your server gets the field osec-captcha-response.
- POST it with your secret to /captcha/siteverify. Accept the form only if success is true.
- Coming from reCAPTCHA: change the script, the field name and the verify URL. The response shape is the same.
html
<form action="/contact" method="post">
<input name="email">
<div class="osec-captcha" data-sitekey="osk_YOUR_SITEKEY"></div>
<button>Send</button>
</form>
<script src="https://osec.one/assets/osec-captcha/osec-captcha.js" async defer></script>bash: verify on your server
curl -X POST https://api.osec.one/tools/captcha/siteverify -d secret=oss_YOUR_SECRET -d response="$OSEC_CAPTCHA_RESPONSE"
# {"success": true, "error-codes": [], "challenge_ts": "..."}- Each solution works once and expires after 10 minutes.
- Error codes: invalid-input-secret, missing-input-response, invalid-input-response, timeout-or-duplicate, sitekey-mismatch.
- Verification calls are not counted against your daily quota. They are limited to 10 per second per IP address.
- Difficulty per key (Site keys → Snippets). It rises automatically for IPs that ask for many puzzles.
- JS API: osecCaptcha.render(el, {sitekey}), osecCaptcha.getResponse(), osecCaptcha.reset(), data-callback="fn".
osec Bot Gate
Middleware on your own server. New visitors solve one invisible check, then browse for 7 days. Search engines pass. Nothing is proxied through us.
- Create a site key; keep the secret in an environment variable.
- Download the middleware for your stack (Node, Python or PHP) and add two lines.
- Deploy. Visitors without the gate cookie see "Checking your browser…" for about a second.
- Visitor passes are not counted against your daily quota.
node (express)
// https://osec.one/assets/osec-gate/osec-gate.js
const osecGate = require("./osec-gate");
app.use(osecGate({ sitekey: "osk_...", secret: process.env.OSEC_SECRET }));python (fastapi / flask)
# https://osec.one/assets/osec-gate/osec_gate.py
from osec_gate import OsecGateASGI, OsecGateWSGI
app.add_middleware(OsecGateASGI, sitekey="osk_...", secret=os.environ["OSEC_SECRET"])
# Flask: app.wsgi_app = OsecGateWSGI(app.wsgi_app, sitekey="osk_...", secret=os.environ["OSEC_SECRET"])php / wordpress (top of wp-config.php)
// https://osec.one/assets/osec-gate/osec-gate.php
require __DIR__ . '/osec-gate.php';
osec_gate(['sitekey' => 'osk_...', 'secret' => getenv('OSEC_SECRET')]);- Only HTML page views (GET/HEAD with Accept: text/html) are gated. APIs, assets, POSTs and feeds pass: protect forms with osec Captcha.
- Crawlers (Google, Bing, DuckDuckGo, Apple, Yandex, Baidu, social previews) pass by user agent. Set verifyCrawlers / verify_crawlers to confirm them by reverse DNS.
- The cookie is signed with your secret and tied to the browser's user agent.
- If osec.one can't be reached, visitors get through for an hour (failOpen / fail_open, on by default).
- It raises the cost of scraping; it doesn't stop a determined attacker running real browsers.
osec Login Protection
Rules osec Auth applies before sending or accepting a sign-in code, and before finishing a Google or Apple sign-in. Not metered.
- Console → Login protection → pick your project.
- Set limits: codes per IP and per email per hour, wrong codes per IP per hour.
- Optional: IP deny list, IP allow list (e.g. office only), allowed email domains, block disposable emails.
- Save. Rules apply within 30 seconds. Blocked attempts show in the same page.
- IP lists, allowed email domains and disposable-email blocking also apply to Google and Apple sign-in. Code limits apply to email codes.
- Blocked users see a clear message in the sign-in dialog (e.g. "Too many sign-in codes requested. Try again in an hour.").
- If the rule check is ever unavailable, sign-in keeps working (fail open).
Site keys
- Console → Site keys → New key. Name it and list your hostnames (empty = any).
- Copy the secret right away: it's shown once. Store it on your server only.
- The sitekey (osk_…) is public: widgets and report URLs use it.
- Server-to-server calls send the secret in the X-Osec-Secret header.
osec Scan (headers + TLS grade)
- Open osec.one/tools/scan and enter a URL.
- Fix the red items with the nginx or Apache snippet under each.
- Scan again. Share the result link with your team or host.
bash
curl -X POST https://api.osec.one/tools/scan -H "Content-Type: application/json" -d '{"url": "example.com"}'- 5 free scans a day without an account. Signed in, each scan counts as 1 request.
osec Monitor (uptime, SSL, domain)
- Console → Monitors → Add monitor. Enter the URL and an optional keyword that must appear on the page.
- Pick the interval: 15 min on free, down to 5 min with credits.
- Set the SSL and domain warning days (defaults 14 and 30).
- Turn on the public status page if you want a link to share.
- Down = two failed checks in a row. You get one email when it goes down and one when it's back.
- Each check counts as 1 request: one monitor every 15 min = 96 a day.
osec CSP Reports
- Create a site key and list your hostnames.
- Add the report URL to your Content-Security-Policy header (start with Report-Only).
- Console → CSP reports shows grouped violations. New ones are emailed to you.
- Allow what's legit in your policy, investigate the rest.
nginx
add_header Content-Security-Policy-Report-Only "default-src 'self'; script-src 'self' https://www.googletagmanager.com; report-uri https://api.osec.one/tools/csp/r/YOUR_SITEKEY; report-to osec" always;
add_header Reporting-Endpoints 'osec="https://api.osec.one/tools/csp/r/YOUR_SITEKEY"' always;- Each report counts as 1 request. Over quota, reports are dropped quietly.
osec Signup Checks API
- Create a site key; use its secret from your server.
- Before creating an account, check the email and the password's SHA-1.
- Reject verdict=reject emails and pwned passwords; ask for another.
bash
# email: disposable, MX, role address, free provider
curl -X POST https://api.osec.one/tools/check/email -H "X-Osec-Secret: oss_..." \
-H "Content-Type: application/json" -d '{"email": "someone@mailinator.com"}'
# {"disposable": true, "mx": true, "role": false, "verdict": "reject", ...}python: breached password (k-anonymity)
import hashlib, requests
sha1 = hashlib.sha1(password.encode()).hexdigest().upper()
r = requests.post("https://api.osec.one/tools/check/password", headers={"X-Osec-Secret": SECRET},
json={"sha1_prefix": sha1[:5]}).json()
pwned = any(s["suffix"] == sha1[5:] for s in r["suffixes"]) # only 5 chars left your server- Send sha1 (40 chars) for a simple yes/no, or sha1_prefix (5 chars) so the full hash never leaves your server.
osec Fingerprint Lite
A stable visitor ID per browser, from browser signals and no cookies. Identify calls count against your daily quota.
- Console → Site keys → New key. List your hostnames (empty = any). Copy the secret once.
- Add the script with your sitekey (osk_…) to the pages you want to identify.
- Listen for the osec-fp event in the browser and send visitor_id with your own form or request.
- From your server, look a visitor up with the secret (X-Osec-Secret).
html
<script src="https://osec.one/assets/osec-fp/osec-fp.js" data-sitekey="osk_YOUR_SITEKEY" async></script>
<script>
window.addEventListener("osec-fp", (e) => {
const { visitor_id, match, suspect } = e.detail; // match: exact | similar | new
});
</script>bash: look up a visitor
curl -s https://api.osec.one/tools/fp/lookup -H "Content-Type: application/json" -H "X-Osec-Secret: oss_YOUR_SECRET" -d '{"visitor_id": "fpl_..."}'- match: exact (same signals as before), similar (11 of 12 signals equal, seen in the last 30 days) or new.
- suspect: true when bot hints are present (webdriver, headless browser in the user agent, no canvas, no hardware info). bot_signals lists them.
- Visitor records are deleted 30 days after their last visit.
- Errors: 404 unknown sitekey, 403 host not in the key's list, 429 quota used up, 400 no known signals.
- A browser fingerprint is personal data under GDPR and similar laws: say so on your page and get consent where it's required.
osec Edge (bot and attack protection)
Challenge page, WAF, rate limits and shared bans from edges in the US and Europe. Full guide per connect mode: osec.one/docs/edge.
- Console → Edge sites → Add site: hostnames, nearest edge (US or EU), connect mode.
- Copy the secret (shown once).
- Open Connect under the site and paste the snippet: nginx, Caddy, Traefik, Apache, Express, FastAPI, WordPress, form widget, log agent or full proxy.
- No DNS change except in full proxy mode.
- Both edges down: your site keeps serving (fail open).
Quota, credits and errors
- Free: 500 metered requests a day per account, reset at 00:00 UTC.
- Emails at 80% and 100%. Past the limit: HTTP 429 {"detail": {"error": "quota_exceeded"}}.
- Credits: $10 = 20 credits. Each adds 500 requests a day for 30 days. Packs stack.
- Buy from Pricing or Console → Usage & billing.