Authentication & API Keys

note

API paths that contain tenant keep that word for compatibility. In the product it means your workspace.

Dralvia exposes customer API paths behind the same edge host (dralvia.tech) so you can keep routing and authentication consistent:

Access type	Base path	Intended for
Guest	`/api/guest`	Public/unauthenticated flows (strictly rate limited).
Workspace	`/api/tenant`	Workspace workloads and integrations using a workspace API key.

For customer integrations, call the workspace base path (/api/tenant/...) instead of legacy routes (/api/...) so edge rate limits and workspace access rules apply consistently.

API versioning (`/v1`)

The public API is versioned so your integration will not break under you. Call the core endpoints under the /v1 prefix, which is the stable, frozen contract:

Endpoint	Versioned path
Scan a URL or domain	`POST /api/tenant/v1/scan`
Unified scan (URL, wallet, contract, hash, email)	`POST /api/tenant/v1/unified/scan`
Repository archive scan	`POST /api/tenant/v1/repo/scan/upload`
Secure Web Gateway evaluate	`POST /api/tenant/v1/swg/evaluate`
Email protect	`POST /api/tenant/v1/email/protect`
Webhooks (list, create)	`GET` and `POST /api/tenant/v1/pro/webhooks`
Webhooks (delete, test)	`DELETE /api/tenant/v1/pro/webhooks/{id}` and `POST /api/tenant/v1/pro/webhooks/{id}/test`

The unversioned paths (for example /api/tenant/scan) still work for backward compatibility and return the same result, but new integrations should pin to /v1 so future additive changes never affect you. When a breaking change is ever needed, it will ship under a new version prefix, not by changing /v1.

Generate an API key

Sign in to the portal: https://dralvia.tech/#/api-keys
Review the first-screen status summary so you know whether you are creating a first key, renewing an existing key, or rotating one already in use.
Click Generate API Key
Copy the key immediately (it is shown once)

Keys are stored hash-only in Postgres; Dralvia cannot show the raw key again. If you lose it, rotate or generate a new key.

The #/api-keys route now surfaces:

a guest sign-in gate when you are not authenticated
a no-key bootstrap state when the workspace has not generated a key yet
an active-key summary showing prefix, expiry, plan tier, quota use, and auto-renew state
an explicit one-time reveal panel after generate/rotate actions

These are presentation changes only. The backend key lifecycle endpoints and workspace scope rules are unchanged.

Send the key in requests

Preferred header:

Authorization: Api-Key <your_key>

Also supported (legacy):

X-API-KEY: <your_key>

Optional audit tag (recommended for CI and automation):

X-Actor: <string>

Example:

curl -sS -X POST "https://dralvia.tech/api/tenant/v1/scan" \
  -H "Authorization: Api-Key $DRALVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Actor: release-ci" \
  -d '{"domain": "example.com"}'

Every endpoint that changes data needs a credential

Signal-ingestion endpoints (for example workspace sign-in signals and endpoint telemetry) require a credential on every request, exactly like the scan endpoints. Send a workspace API key, or call from a signed-in session.

A request with no credential is rejected before the body is read:

{
  "error": "unauthorized",
  "detail": "Authentication required.",
  "reason": "credentials_required"
}

Two things follow from this, and both matter if you are writing a collector or an agent:

The workspace is taken from your credential, not from your payload. A tenant_id in the request body cannot direct data into another workspace.
A rejected request writes nothing. If you get a 401, retry with a valid key rather than assuming partial delivery.

The public scan tools stay open. Guest scanning under /api/guest needs no account and is unaffected.

Signed-in browser sessions

Most integrations should use workspace API keys. Signed-in browser sessions are for the Dralvia portal and customer-controlled interactive workflows. If you are building a browser-based integration, contact Dralvia support for the recommended session flow instead of copying tokens from the browser.

Do not paste browser session tokens into scripts, CI jobs, or shared notebooks.

Limits and plan tiers (high level)

API key limits are enforced by plan tier (quota + key caps). Defaults:

Free Evaluation: 25 scans/month, 1 key/workspace, 1 key/user, 10 rpm
Starter: 1,000 scans/month, 1 key/workspace, 1 key/user, 60 rpm
Pro: 10,000 scans/month, 3 keys/workspace, 3 keys/user, 300 rpm
Usage-based Enterprise: metered scan quota, up to 5 keys/workspace, 3 keys/user
Enterprise: custom

When you exceed a limit, the API returns a structured error with an actionable detail and the limit.

Lifecycle operations

From the portal you can:

Renew an existing key (extends expiry)
Rotate a key (shows the new key once; old key may remain valid for a short grace window)
Revoke a key (immediately invalid)
Toggle auto-renew so the key renews ahead of expiry without changing the request format your integrations send

Security guidance

Treat API keys like passwords: store them in Vault/your secret manager and never commit them to git.
Prefer separate keys per integration (CI, ticketing, SIEM) so you can rotate without breaking everything.
Rotate immediately if you suspect exposure (logs, screenshots, browser console).

API versioning (/v1)​

Generate an API key​

Send the key in requests​

Every endpoint that changes data needs a credential​

Signed-in browser sessions​

Limits and plan tiers (high level)​

Lifecycle operations​

Security guidance​