Authentication
The API authenticates with an API key sent in the
X-Api-Key header on every request.
curl https://api.urlyze.io/api/usage -H "X-Api-Key: YOUR_API_KEY"Creating a key
Keys are created in the dashboard: app.urlyze.io → Settings → API keys. The plaintext key is shown once at creation — store it securely. Keys can be given an expiry date and revoked at any time.
Scopes
Each key carries one or more scopes that bound what it can do:
| Scope | Grants |
|---|---|
ScanWrite | Submit URLs for scanning. |
ScanRead | Read scan results and your scan list; fetch screenshots. |
SearchRead | Pivot search across fingerprints. |
IocExport | Read the tenant IOC feed (JSON / STIX / EDL). |
A newly created key defaults to ScanWrite + ScanRead + SearchRead.
Anonymous access & visibility
Scan submission and result polling also work without a key, with two important differences:
| Anonymous | With API key | |
|---|---|---|
| Scan visibility | Always "Public" — the scan appears in the community feed. |
Defaults to "Private"; you may set "Private",
"Unlisted" or "Public" per submission. |
| Rate limits | Strict, per IP. | Per key, per your plan. |
Submitting a URL anonymously publishes it. If a URL may contain
private tokens or belongs to an internal system, always submit it with an API key
and private visibility.
Reading a private scan without access rights returns 404 (not
403) — the API does not reveal whether a private scan exists.