CanYouGrab.it

CanYouGrab API

Domain availability lookup API with subscription billing, built on FastAPI + DNS (Unbound resolver).

Live services:

• API: https://api.canyougrab.it
• Developer portal: https://portal.canyougrab.it
• Auth: https://auth.canyougrab.it (Auth0 custom domain)

Architecture Overview

┌──────────────────────────────────────────────────────────────────┐

│ Developer Portal │ │ (Zudoku/React on portal.canyougrab.it) │ │ Usage Dashboard · API Keys · Pricing · API Reference (OAS) │ └──────────────────┬───────────────────────────────────────────────┘ │ Auth0 JWT (portal) / Bearer API key (API) ▼ ┌──────────────────────────────────────────────────────────────────┐ │ FastAPI Backend (v5.0.0) │ │ api.canyougrab.it:8000 │ │ │ │ ┌─────────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │ │ │ app.py │ │ keys.py │ │billing.py│ │ auth.py │ │ │ │ /check/bulk │ │ /keys │ │/billing │ │ API key + │ │ │ │ /usage │ │ CRUD │ │/stripe │ │ JWT auth │ │ │ │ │ │ rotate │ │ webhook │ │ │ │ │ └──────┬──────┘ └──────────┘ └────┬─────┘ └─────────────┘ │ │ │ │ │ └─────────┼────────────────────────────┼───────────────────────────┘ │ │ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ │ Valkey (Redis) │ │ Stripe API │ │ Job queue + │ │ Subscriptions │ │ Rate limiting │ │ Webhooks │ └────────┬────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ ┌──────────────────────────────┐ │ RQ Worker │──DNS──▶ │ Unbound Resolver │ │ (worker.py) │ │ (dedicated droplet) │ │ ThreadPool(10) │ │ NS queries via VPC │ │ via RQ queue │ └──────────────────────────────┘ └─────────────────┘ ┌──────────────────────────────┐ ───────────────────▶│ PostgreSQL │ (auth, usage, │ API keys + Usage logs │ billing only) └──────────────────────────────┘

Directory Structure

zuplo/

├── backend/ # Python FastAPI backend │ ├── app.py # Main API: /check/bulk, /usage, /health │ ├── auth.py # API key auth (SHA-256) + Auth0 JWT auth (RS256) │ ├── billing.py # Stripe checkout, portal, webhooks, card-on-file, usage details │ ├── keys.py # API key CRUD: create, list, rotate, revoke (+ Turnstile) │ ├── antifraud.py # Anti-fraud: Turnstile, device fingerprints, risk scoring │ ├── email_utils.py # Email normalization + disposable email detection │ ├── dns_client.py # DNS-based domain availability checking via Unbound │ ├── queries.py # PostgreSQL queries: usage tracking, auth, billing │ ├── valkey_client.py # Redis/Valkey job queue client (RQ-backed) │ ├── rq_tasks.py # RQ task function: process_domain_job() │ ├── worker.py # RQ worker process (ThreadPoolExecutor per job) │ ├── migrations/ # SQL migrations │ │ └── 001_free_tier_antifraud.sql │ └── requirements.txt # Python dependencies ├── portal/ # Developer portal (Zuplo + Zudoku) │ ├── config/ │ │ ├── routes.oas.json # OpenAPI 3.1 spec (public API documentation) │ │ └── policies.json # Zuplo policies (empty — all routing is direct) │ ├── docs/ # Zudoku documentation portal │ │ ├── src/ │ │ │ ├── config.ts # API_BASE, Turnstile site key, Stripe PK │ │ │ ├── UsageDashboard.tsx # Usage + billing dashboard component │ │ │ ├── PricingPage.tsx # Plan selection + Stripe checkout │ │ │ ├── PricingPlans.tsx # Pricing card grid component │ │ │ └── CardSetupPage.tsx # Stripe Elements card-on-file for Free+ │ │ ├── public/ # Static assets (logos, banners, CSS overrides) │ │ ├── zudoku.config.tsx # Portal config: theme, nav, Auth0, API key mgmt │ │ └── package.json # Frontend dependencies (React 19, Zudoku) │ ├── package.json # Workspace root (Zuplo v6, TypeScript v5) │ └── README.md # Zuplo boilerplate (not project-specific) ├── mcp-server/ # MCP package for ChatGPT, Claude, and remote MCP clients │ ├── pyproject.toml # MCP package metadata + version │ ├── server.json # MCP registry/server metadata │ ├── uv.lock # Locked MCP runtime dependencies │ └── src/canyougrab_mcp/ │ ├── init.py │ └── server.py # stdio + streamable-http MCP entrypoint ├── .github/workflows/ │ ├── deploy.yml # Production deploy (on tag push v*) │ └── deploy-dev.yml # Dev deploy (on push to dev branch) ├── .claude/ │ └── launch.json # Local dev server config (port 9200) └── package.json # Root workspace config

API Endpoints

Public API (API key auth: Authorization: Bearer cyg_...)

Portal API (Auth0 JWT auth)

Internal / Webhook

Core Request Flow

Domain Availability Check

Client                    FastAPI                     Valkey                      Worker              Unbound

│ │ │ │ │ │ POST /api/check/bulk │ │ │ │ │ { domains: [...] } │ │ │ │ │─────────────────────────▶│ │ │ │ │ │── validate key ──────────│ │ │ │ │── check minute rate ────▶│ INCR ratelimit:id:min │ │ │ │── check monthly quota ──▶│ (PostgreSQL) │ │ │ │── record usage ─────────▶│ (PostgreSQL) │ │ │ │── create_job() ─────────▶│ HSET job:{uuid} │ │ │ │ │ RQ enqueue (with retry) │ │ │ │ │ │ │ │ │ │◀── RQ Worker dequeues ───│ │ │ │ │ │ │ │ │ │──── claim_job() ────────▶│ │ │ │ │ │── ThreadPool(10) │ │ │ │ │── check_domain_dns() │ │ │ │── NS query ───────▶│ │ │ │ │◀── NOERROR/NXDOMAIN│ │ │ │◀── complete_job() ───────│ │ │ │ │ │ │ │ │◀─ poll get_job_status() ─│ │ │ │ │ (0.3s interval, 30s │ │ │ │ │ max timeout) │ │ │ │◀─────────────────────────│ │ │ │ │ { results: [...] } │ │ │ │

Billing / Subscription Flow

User → Pricing Page → Select Plan → Auth0 login

→ POST /api/billing/checkout (JWT auth) → Find/create Stripe customer (linked by auth0_sub metadata) → Stripe Checkout Session created → redirect to Stripe → User pays → Stripe fires webhook → POST /api/stripe/webhook (HMAC-SHA256 verified) → checkout.session.completed → fetch subscription → get price ID → Map price to plan → UPDATE api_keys SET plan, lookups_limit

Subscription Plans

Authentication

API Key Auth (public API consumers)

• Format: Authorization: Bearer cyg_
• Keys are SHA-256 hashed in the api_keys table (plaintext never stored)
• Key prefix (cyg_XXXXXXXX...) is stored for display in the portal
• Full key returned only once at creation time
• Soft-delete on revocation (revoked_at timestamp, not physically deleted)

JWT Auth (portal/dashboard)

• Auth0 tenant: dev-mqe5tavp6dr62e7u
• Custom domain: auth.canyougrab.it
• Algorithm: RS256 with JWKS validation (1-hour cache)
• Audience: https://api.canyougrab.it
• Social logins: Google, Apple (Sign in with Apple)

Domain Availability via DNS

Domain availability is checked by querying a dedicated Unbound recursive DNS resolver running on a separate DigitalOcean droplet. The worker sends NS record queries over the VPC private network and interprets the response:

| DNS Response | `avail