Authentication

Try this endpoint in the playground →

Learn how to authenticate your requests to the DFIR Platform API.

API Keys

All API requests require authentication via an API key. Without a valid key, requests will return a 401 Unauthorized error.

API keys are created in the platform dashboard at /api-keys. Each key is scoped to your organization and can be configured with specific permissions.

Key format

sk-dfir-{32 alphanumeric characters}

API keys are displayed only once at creation. Copy and store your key securely immediately — it cannot be retrieved later.

Using Your Key

Pass your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer sk-dfir-your-key

cURL

bash
curl -X POST https://api.dfir-lab.ch/v1/phishing/dns \
  -H "Authorization: Bearer sk-dfir-your-key" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Python

python
import requests

response = requests.post(
    "https://api.dfir-lab.ch/v1/phishing/dns",
    headers={"Authorization": "Bearer sk-dfir-your-key"},
    json={"domain": "example.com"}
)

Permissions

Each API key can be scoped with specific permission levels. Use the minimum permissions required for your use case.

ScopeDescription
phishing:readAccess phishing lookup endpoints — DNS, blacklist, Safe Browsing, URL expand, CheckPhish, GeoIP, urlscan, and IOC enrichment
phishing:analyzeSubmit raw emails for heuristic phishing analysis
phishing:aiAccess the AI-powered phishing verdict endpoint (/analyze/ai). Requires Starter plan or above.
enrichment:readEnrich IOCs (IPs, domains, URLs, hashes) against threat intelligence providers
exposure:readAccess exposure scan endpoints
api:fullFull access to all API endpoints — equivalent to granting every scope

For the complete permission reference — including scope expansion, endpoint mapping, and common permission sets — see the Permissions page.

Security Best Practices

  • 1

    Never commit keys to version control

    Add your key files to .gitignore and never hardcode keys in source files.

  • 2

    Use environment variables

    Store keys in environment variables (e.g. DFIR_API_KEY) and load them at runtime.

  • 3

    Rotate keys periodically

    Create new keys and revoke old ones on a regular schedule. Set expiration dates when creating keys to enforce automatic rotation.

  • 4

    Use minimum required permissions

    Follow the principle of least privilege. Only grant the scopes your integration actually needs — avoid using api:full unless absolutely necessary.