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.
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.
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.
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.
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 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.
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_..."
| Who | Basic scans | Deep scans |
|---|---|---|
| Anonymous | 10/min per IP | — |
| With an API key | 1,000/month | 5/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.
| Action | Limit |
|---|---|
| Anonymous basic scan | 10/min per IP |
| Keyed scan (basic or deep) | 1,000/month per key |
| Deep scan burst | 5/min per account |
| Any single target, all scans combined | 500/day |
| Domain verify — start | 20/min per key |
| Domain verify — check | 10/min per key |
| Reads (scan/findings/status lookups) | 120/min per IP or key |
| MCP client registration | 10/hour per IP |
Hit a limit and you'll get a 429 with a retry_after in seconds.
Get a POST when a scan finishes for a domain your account owns.
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.
Questions or abuse reports: security@tinscan.com
| Endpoint | Auth | Params |
|---|---|---|
POST /api/v1/scans | none, or key for deep | domain (required), scan_type: basic | deep (default basic) |
GET /api/v1/scans/{scan_id} | none | scan_id in path |
GET /api/v1/scans/{scan_id}/findings | none | scan_id in path |
GET /api/v1/domains/{domain}/latest | none | domain in path |
POST /api/v1/domains/{domain}/verify/start | key | domain in path, no body |
POST /api/v1/domains/{domain}/verify/check | key | domain in path; body: method: well_known | dns_txt (required) |
GET /api/v1/domains/{domain}/verification | key | domain in path |
POST /api/account/api-keys | account session | name (default "API Key", max 100 chars), expires_in_days: 1–365 (default 1 if omitted) |
GET /api/account/api-keys | account session | — |
DELETE /api/account/api-keys/{id} | account session | id in path |
All responses are JSON. Errors look like:
{"error": "domain_not_verified", "message": "..."}
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"
}