Connect With TinScan

Use MCP with AI agents, or the API for automation

Everything the website can do, your code can do too. An API key is free with any account.

Connect an AI agent (MCP)

Claude.ai (easiest): open TinScan in the Connectors Directory and click Connect. It is a Community connector, so Claude shows a short reminder first.

Any other MCP-compatible agent, or Claude.ai without the directory, points at:

https://tinscan.com/mcp

In Claude.ai: Settings → Connectors → Add custom connector, paste that URL, and click Add.

Claude may preselect "No sign-in" because basic scans work without an account. That is fine: when you use a tool that needs an account, Claude asks you to sign in. If it ever doesn't, set Authentication to "Sign in when needed".

Basic scans work right away, with no account. When you ask for something that needs one, such as a deep scan or domain verification, Claude asks you to sign in. The sign-in lasts 90 days. After that, or if you revoke it, Claude asks again.

Connecting a CLI or self-hosted agent instead of Claude.ai

Skip the sign-in flow and use an API key as a plain bearer header:

{
  "mcpServers": {
    "TinScan": {
      "url": "https://tinscan.com/mcp",
      "headers": { "Authorization": "Bearer tsk_..." }
    }
  }
}

Exact config shape depends on your client — this is the general pattern.

Scan a site

Prefer plain HTTP over MCP? No account or key needed for a basic scan — same limit as the website.

curl -X POST https://tinscan.com/api/v1/scans \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'
curl https://tinscan.com/api/v1/domains/example.com/latest

10 scans/minute per IP — shared with the website, so it stacks with whatever you've already run there.

Get an API key

Sign in, then create one. It's shown once — save it somewhere safe.

curl -X POST https://tinscan.com/api/account/api-keys \
  -H "Content-Type: application/json" \
  -b "tinscan_session=..." \
  -d '{"name": "my project"}'

# {"key": "tsk_...", "id": 7, "name": "my project", ...}

Keys expire in 1 day by default. Pass "expires_in_days": 30 (up to 365) for a longer-lived key. You can also create and revoke keys, and see the apps you have connected, on the Keys page.

From here, send it as a normal bearer token on any /api/v1 or MCP request:

curl -X POST https://tinscan.com/api/v1/scans \
  -H "Authorization: Bearer tsk_..." \
  -d '{"domain": "example.com"}'

Deep scan your own domain

Deep scans probe further than a basic scan, so we ask you to prove you own the domain first — once per domain, not once per scan.

curl -X POST https://tinscan.com/api/v1/scans \
  -H "Authorization: Bearer tsk_..." \
  -d '{"domain": "example.com", "scan_type": "deep"}'

# 401 auth_required if there's no key, 403 if the domain isn't verified yet

Verify once on the website and every key on your account can deep-scan that domain afterward.

Verify a domain from code instead (for automation, CI, no browser)

Same result as the website's verify step, just callable directly. Requires a key.

curl -X POST https://tinscan.com/api/v1/domains/example.com/verify/start \
  -H "Authorization: Bearer tsk_..."

# returns a DNS TXT record or a .well-known file to place
curl -X POST https://tinscan.com/api/v1/domains/example.com/verify/check \
  -H "Authorization: Bearer tsk_..." \
  -d '{"method": "well_known"}'   # or "dns_txt"
curl https://tinscan.com/api/v1/domains/example.com/verification \
  -H "Authorization: Bearer tsk_..."

Limits

WhoBasic scansDeep scans
Anonymous10/min per IP—
With an API key1,000/month5/min per account

Every target is also capped at 500 scans/day total, across everyone — one popular domain can't be hammered by spinning up many keys.

Full limits reference
ActionLimit
Anonymous basic scan10/min per IP
Keyed scan (basic or deep)1,000/month per key
Deep scan burst5/min per account
Any single target, all scans combined500/day
Domain verify — start20/min per key
Domain verify — check10/min per key
Reads (scan/findings/status lookups)120/min per IP or key
MCP client registration10/hour per IP

Hit a limit and you'll get a 429 with a retry_after in seconds.

Webhooks

Get a POST when a scan finishes for a domain your account owns.

Register a webhook and verify deliveries

Register an https URL with your signed-in session. The secret is shown once.

POST /api/account/webhooks
{"name": "ci", "url": "https://example.com/hooks/tinscan"}

The URL must resolve to a public address. Private, loopback and cloud-metadata addresses are refused.

Each delivery is a POST with these headers:

X-TinScan-Event: scan.completed
X-TinScan-Timestamp: 1763100000
X-TinScan-Signature: sha256=<hex>

The signature is HMAC-SHA256 of <timestamp>.<raw body>, keyed with your secret. Reject deliveries older than five minutes, so a captured one can't be replayed.

import hmac, hashlib, time

def verify(secret, timestamp, body, signature):
    if abs(time.time() - int(timestamp)) > 300:
        return False  # too old
    signed = timestamp.encode() + b"." + body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

The body:

{
  "event": "scan.completed",
  "scan_id": "8c407c4b-1626-4f20-afc6-5d9137568f0a",
  "domain": "example.com",
  "status": "done",
  "scan_type": "basic",
  "grade": "C",
  "findings_count": 10,
  "error": null,
  "timestamp": "2026-11-14T03:02:13Z"
}

One attempt per delivery, no retries. GET /api/account/webhooks shows each webhook's last result. You can manage them on the Keys page too.


Scan policy

Questions or abuse reports: security@tinscan.com

Full API reference
EndpointAuthParams
POST /api/v1/scansnone, or key for deepdomain (required), scan_type: basic | deep (default basic)
GET /api/v1/scans/{scan_id}nonescan_id in path
GET /api/v1/scans/{scan_id}/findingsnonescan_id in path
GET /api/v1/domains/{domain}/latestnonedomain in path
POST /api/v1/domains/{domain}/verify/startkeydomain in path, no body
POST /api/v1/domains/{domain}/verify/checkkeydomain in path; body: method: well_known | dns_txt (required)
GET /api/v1/domains/{domain}/verificationkeydomain in path
POST /api/account/api-keysaccount sessionname (default "API Key", max 100 chars), expires_in_days: 1–365 (default 1 if omitted)
GET /api/account/api-keysaccount session—
DELETE /api/account/api-keys/{id}account sessionid in path

All responses are JSON. Errors look like:

{"error": "domain_not_verified", "message": "..."}

Sample requests and responses

POST /api/v1/scans — basic (no key needed)

// request
{"domain": "example.com"}

// response
{
  "scan_id": "8c407c4b-1626-4f20-afc6-5d9137568f0a",
  "domain": "example.com",
  "status": "queued",
  "scan_type": "basic",
  "cached": false
}

POST /api/v1/scans — deep (key + verified domain required)

// request
{"domain": "example.com", "scan_type": "deep"}

// response
{
  "scan_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "domain": "example.com",
  "status": "queued",
  "scan_type": "deep"
}

GET /api/v1/scans/{scan_id} — no request body

// response (findings/result trimmed here for length —
// the real payload includes the full findings list,
// recommendations, DNS records, and more)
{
  "scan_id": "8c407c4b-1626-4f20-afc6-5d9137568f0a",
  "domain": "example.org",
  "scan_tier": "free",
  "scan_mode": "passive",
  "scan_type": "basic",
  "scanned_at": "2026-08-27T03:18:55Z",
  "is_verified_owner": false,
  "has_deep_scan": false,
  "has_attack_scan": false,
  "result": {
    "summary": {
      "risk_score": 14,
      "health_score": 86,
      "risk_grade": "B",
      "combined_grade": "B",
      "findings_count": 8,
      "top_action": "Add Content Security Policy"
    },
    "findings": [
      {
        "id": "missing_content_security_policy",
        "severity": "info",
        "category": "security_headers",
        "evidence": "content-security-policy header not found"
      }
    ]
  }
}

GET /api/v1/scans/{scan_id}/findings — no request body

// response
{
  "scan_id": "8c407c4b-1626-4f20-afc6-5d9137568f0a",
  "domain": "example.org",
  "scanned_at": "2026-08-27T03:18:55Z",
  "combined_grade": "B",
  "findings_count": 8,
  "severity_counts": {"critical": 0, "high": 0, "medium": 0, "low": 8, "negligible": 0},
  "top_action": "Add Content Security Policy",
  "findings": [
    {
      "id": "missing_content_security_policy",
      "severity": "info",
      "category": "security_headers",
      "evidence": "content-security-policy header not found",
      "title": "Add Content Security Policy"
    }
  ]
}

GET /api/v1/domains/{domain}/latest — no request body; same response shape as GET /api/v1/scans/{scan_id} above, for whichever scan of this domain most recently completed.

POST /api/v1/domains/{domain}/verify/start — no request body

// response
{
  "domain": "example.com",
  "verification_token": "Xk3nP9qRstUvWxYzAbCd",
  "instructions": {
    "dns_txt": {
      "name": "_tinscan.example.com",
      "value": "tinscan-verification=Xk3nP9qRstUvWxYzAbCd",
      "note": "Set TTL to 60 so changes propagate quickly."
    },
    "well_known": {
      "url": "https://example.com/.well-known/tinscan.txt",
      "content": "tinscan-verification=Xk3nP9qRstUvWxYzAbCd",
      "note": "Create this file on your web server. Verification is instant."
    }
  }
}

POST /api/v1/domains/{domain}/verify/check

// request
{"method": "well_known"}

// response — not found yet
{
  "domain": "example.com",
  "verified": false,
  "message": "Token not found in well-known file"
}

// response — success
{
  "domain": "example.com",
  "verified": true,
  "message": "well-known file verified"
}

GET /api/v1/domains/{domain}/verification — no request body

// response
{
  "domain": "example.com",
  "verified": true,
  "method": "well_known",
  "verified_at": "2026-08-27T04:12:00Z"
}

POST /api/account/api-keys

// request
{"name": "my project", "expires_in_days": 30}

// response — "key" is shown exactly once, here, and never again
{
  "id": 7,
  "name": "my project",
  "prefix": "tsk_AbCdEfGh",
  "created_at": "2026-08-27T00:00:00Z",
  "last_used_at": null,
  "expires_at": "2026-09-26T00:00:00Z",
  "revoked_at": null,
  "key": "tsk_AbCdEfGh1234567890KlMnOpQrStUvWxYz"
}

GET /api/account/api-keys — no request body

// response — note: no "key" or hash field on listed keys
{
  "keys": [
    {
      "id": 7,
      "name": "my project",
      "prefix": "tsk_AbCdEfGh",
      "created_at": "2026-08-27T00:00:00Z",
      "last_used_at": "2026-08-27T05:30:00Z",
      "expires_at": "2026-09-26T00:00:00Z",
      "revoked_at": null
    }
  ]
}

DELETE /api/account/api-keys/{id} — no request body

// response
{
  "id": 7,
  "name": "my project",
  "prefix": "tsk_AbCdEfGh",
  "created_at": "2026-08-27T00:00:00Z",
  "last_used_at": "2026-08-27T05:30:00Z",
  "expires_at": "2026-09-26T00:00:00Z",
  "revoked_at": "2026-08-27T06:00:00Z"
}