Developer Integration Guide

If a term is unfamiliar, open the Glossary.

This guide covers how product teams embed Dralvia into their pipelines (CI, ticketing, custom dashboards, browser tooling).

1. Provision credentials

• Generate a workspace-scoped API key in the portal: https://dralvia.tech/#/api-keys (it is shown once).
• Grant the appropriate Dralvia workspace role for engineers. If you need elevated scopes, open a support ticket.
• Store keys in your secret manager and map them to the environments that call Dralvia (CI, staging, prod).

2. Choose an integration path

Option A: REST + SDKs

Use the SDK guides for the concrete client setup path:

1. Sign in and create a workspace API key at https://dralvia.tech/#/api-keys.
2. Store it as DRALVIA_API_KEY and set DRALVIA_BASE_URL=https://dralvia.tech/api/tenant.
3. Install from the public GitHub source at https://github.com/Dralvia/dralvia-sdk.
4. Run a first scan before wiring the client into CI or scheduled jobs.

What a workspace API key can do on its own

A workspace API key works without a signed-in browser session. What it may call is decided by its permissions. Every key has the defaults below; some permissions are never included by default and must be chosen when the key is created or rotated.

Permission	Lets the key	Included
scan	POST /v1/scan, POST /v1/email/protect, POST /agent/check-action, POST /agent/check-content	every plan
unified_scan	POST /v1/unified/scan	Starter, Pro and above
reposcan	POST /v1/repo/scan/upload, and read results: GET /v1/repo/scan/{id}, /ci-gate, /export, /export/manifest, /triage, and POST /v1/repo/scan/{id}/enrich	Starter, Pro and above
usage:read	GET /v1/usage/summary	every key
webhooks	GET/POST /v1/pro/webhooks, DELETE /v1/pro/webhooks/{id}, POST /v1/pro/webhooks/{id}/test	only if chosen
reposcan_triage	Review, suppress and reconcile repository scan findings	only if chosen
swg	POST /v1/swg/evaluate	only if chosen

Why some permissions must be chosen. They change what a leaked key could do. A key with webhooks can send every future scan result to an outside URL; a key with reposcan_triage can hide findings from your CI gate. Not even an Enterprise key gets them without asking.

How to add one. Open API keys in the workspace console, tick the permission under Additional permissions, and choose Rotate key (or Generate API Key for your first key). The new key has the permission; the previous key keeps working through its grace window, so integrations can switch without an outage. Rotation keeps whatever permissions the key already had.

What a key can never do: create, rotate or revoke keys; manage team members; change billing; manage identity, licensing or administration. Those always need a signed-in session, so a leaked key cannot be used to issue more keys or change who has access.

Every key only ever sees its own workspace: asking for another workspace's scan returns 404, and a tenant_id or X-Tenant-ID supplied by the caller is ignored.

Send the key as Authorization: Api-Key <key>. The Python SDK sends X-API-KEY, which is also accepted.

Response	Meaning
401 "reason": "credentials_required"	No key was sent.
401 "error": "not_found"	The key is wrong, revoked or expired.
403 "reason": "api_key_scope_missing"	The key is valid but lacks the permission named in required_scope. Rotate it with that permission.
401 saying that sign-in is required	This endpoint is not available to API keys. It works only in the app, signed in.

Changed on 14 September 2026

Until this date workspace API keys were refused on every workspace endpoint unless the request also carried a signed-in session, so the SDK usage on this page did not work. Keys created before this date keep working and have the default permissions for their plan.

Start with Python SDK or JavaScript SDK. The examples below show the target shape after setup:

from dralvia_sdk import DralviaClient

client = DralviaClient(base_url="https://dralvia.tech/api/tenant", api_key=os.environ["DRALVIA_API_KEY"])
result = client.scan_url("https://example.com", flags={"save_evidencepack": True})

import { DralviaClient } from "@dralvia/sdk";

const client = new DralviaClient({ baseUrl: process.env.DRALVIA_BASE_URL, apiKey: process.env.DRALVIA_API_KEY });
const swgDecision = await client.evaluateSwg("https://example.com/social");

For copy-paste examples that match the strongest first-user workflows, start with First-User Workflows.

Option B: Postman/Newman

Download the Dralvia Postman collection from the Docs portal and import it into Postman or Newman. Set baseUrl + apiKey, then wire Newman into CI for smoke tests.

Option C: TicketBridge + Webhooks

Use the workspace TicketBridge case-ingest API to POST EvidencePack (Dralvia's exportable evidence report) metadata into your case management tooling. Webhook delivery is supported for customer case-management and source-control integrations.

3. Embed in workflows

Workflow	Recommended calls
CI/CD gate	POST /scan for every domain in your release allowlist; fail the build if risk_level ≥ medium.
Browser extension	Use the #/pre-sign APIs to surface DOM intent and Tx simulator data before signing transactions.
SWG inline coaching	Call the workspace Web Access Protection evaluate API when the proxy sees an uncategorized URL, then respect action (allow/warn/block) and coaching_message.
Email review bots	Feed suspicious content into /email/protect with attachments + HTML body.

4. Operational tips

• Rate limits: default 5 req/min for anonymous, 60 req/min for authenticated workspaces. Burst via header X-RateLimit-Remaining.
• Retries: 429 and 5xx responses are safe to retry with exponential backoff.
• EvidencePacks: download via /evidencepacks/<id> or export CSVs from the admin console for analytics.

5. Sample policy

pipelines:
  web2:
    command: curl -sS -H "Authorization: Api-Key $DRALVIA_KEY" \
      -H "Content-Type: application/json" \
      -d "{\"url\": \"${TARGET_URL}\"}" \
      "$DRALVIA_BASE/scan"
    fail_on_risk_levels: ["high", "critical"]

Install the SDK from the public registries (npm install @dralvia/sdk, pip install dralvia-sdk), from the public GitHub source at https://github.com/Dralvia/dralvia-sdk, or mirror it into your internal package registry, so every team shares the same retries, timeouts, and auth headers.

Who this is for

This guide is for workspace owners, workspace admins, and security operators who need clear, repeatable steps without support intervention for day-to-day execution.

Role-based start here

• Workspace Owner: Start with Before you start, then complete Step-by-step and Known limits and rate limits.
• Workspace Admin: Focus on Step-by-step, What each button does, and API and automation.
• Security Analyst: Start at Day-2 operations and Troubleshooting, then use API error quick reference.
• Integrator/Engineer: Start at API and automation, then validate with Step-by-step and FAQ.

Before you start

Use this short checklist before making changes:

1. Confirm you are signed into the correct workspace account.
2. Confirm your role includes the permissions needed for this page.
3. Confirm your browser session is fresh (if pages behave unexpectedly, sign out/in once).
4. Confirm required prerequisites (API keys, agent enrollment, license, upstream integrations) are already in place.

Step-by-step

Follow this sequence for predictable results:

1. Open the workspace from the workspace menu.
2. Review current status/health/last update indicators before making changes.
3. Apply one change at a time and save.
4. Run the available validate/probe/refresh action.
5. Confirm the expected output appears (status change, new event, successful result).
6. If behavior is not as expected, use Troubleshooting below before repeating actions.

Day-2 operations

After initial setup, keep this surface healthy with a simple routine:

1. Daily: verify data freshness and error banners.
2. Weekly: review trends, limits, and failed actions.
3. Monthly: review permissions, keys/tokens, and stale entities.
4. After any incident: capture evidence and update your internal operating notes.

What each button does

Button labels can vary by module, but behavior is consistent:

• Refresh: reloads the latest data from backend APIs without changing configuration.
• Save: persists workspace-scoped configuration changes.
• Run/Probe/Validate: executes a non-destructive health or verification action.
• Download: fetches workspace-scoped artifact(s) (for example bundle, checksum, signature, or report).
• Verify: checks integrity/consistency and returns pass/fail details.
• Enable/Disable: toggles module behavior for your workspace; audit evidence should be recorded.

If a button appears disabled, check role permissions, required fields, and workspace license/feature entitlement first.

Self-check playbook

Use this 5-step isolation flow before escalating:

1. Configuration: confirm required inputs are present and formatted correctly.
2. Permission: confirm your role can perform the action (401/403 usually indicates authz/authn mismatch).
3. License/feature: confirm the feature is enabled for your workspace plan and module toggles.
4. Quota/rate limit: check for 429 responses and cooldown windows.
5. Service health: if you see 5xx, retry once after 30-60 seconds and capture exact error text.

If still failing, escalate with workspace ID, UTC timestamp, route, action, payload shape (no secrets), and screenshot/error response.

Troubleshooting

Use this quick triage order to reduce time-to-fix:

1. Auth/session: refresh token by signing out/in.
2. Workspace context: confirm you are in the correct workspace.
3. Inputs/config: verify required fields and formats.
4. Quota/license: confirm limits and feature entitlement.
5. Service health: retry after short delay if backend is transiently degraded.

For escalation, include workspace ID, timestamp (UTC), route name, action attempted, and full error message.

API and automation

Everything in this page should remain workspace-scoped. If your team prefers automation, use the corresponding API endpoints with the same guardrails as the UI:

• Use authenticated requests bound to your workspace context.
• Use idempotency/retry controls where available.
• Validate outcomes in the UI after automated runs.

If your endpoint mapping is not obvious, start from Help Center and follow the linked API docs.

Next best actions

After finishing this page, continue with related workflows so your workspace setup stays end-to-end complete:

• EDR response and host actions
• Web Access Protection and dry-run events
• Identity risk and OAuth response
• EvidencePack verification and transparency log
• Risk economics and plan recommendation

FAQ

Q: I clicked save but nothing changed. A: Refresh once, confirm permissions, and verify required fields.

Q: Why do I see missing API key/unauthorized errors? A: Confirm your workspace API key/session is valid and mapped to the correct workspace scope.

Q: Can non-admin users use this page? A: Usually read-only access is possible; write actions require workspace-admin or equivalent roles.

Next steps

After finishing this guide:

1. Validate the result in the related dashboard/workspace.
2. Export or capture evidence if this affects compliance/incident operations.
3. Share the same runbook internally so other operators follow identical steps.
4. Return to Help Center for adjacent workflows.

API error quick reference

Use this matrix when a UI action fails with an HTTP/API error.

Error	Meaning	What to do now
401 Unauthorized	In the app: your session is missing or expired. From the API or an SDK: no workspace API key was sent (reason: credentials_required), or the key is wrong, revoked or expired.	In the app, sign out/in and retry. From code, send the key as Authorization: Api-Key <key> (the SDK's X-API-KEY header also works) and confirm it has not been revoked or rotated.
402 Payment Required	The monthly quota for the plan is spent, or payment is in a failed state.	Not a pacing problem: retrying will not clear it. Check plan usage and billing status.
403 Forbidden	In the app: your role is not allowed to perform this action. From the API: the API key lacks a permission (reason: api_key_scope_missing, with required_scope).	In the app, ask a workspace admin to grant access. From code, rotate the key under API keys with the permission named in required_scope.
404 Not Found	The route/resource does not exist in current workspace context (or feature not enabled).	Confirm URL/route, workspace context, and feature availability. Refresh and retry; if persistent, capture timestamp and route and contact support.
429 Too Many Requests	The API key exceeded its plan's requests-per-minute rate.	Wait the retry_after_seconds returned in the body, then retry. Add backoff/jitter if automated. This does not consume monthly quota.
500 Internal Server Error	Backend failed unexpectedly while processing the request.	Retry after 30-60 seconds. If still failing, escalate with workspace ID, UTC time, route, action, and full error text.

Known limits and rate limits

There are two separate limits on an API key, and they fail differently.

Requests per minute, by plan

Every API key is limited to a number of requests per minute set by its plan. Exceeding it returns 429 Too Many Requests with a retry_after_seconds field telling you how long is left in the current window.

Plan	Requests per minute
Free / Evaluation	10
Starter	60
Pro, Pay-as-you-go	300
Enterprise	300

The window is a fixed clock minute, not a rolling one: the counter resets at the top of each minute rather than sixty seconds after your first request.

A 429 from this limit does not consume anything from your monthly quota. Throttled requests are free.

Monthly quota

Separately, a plan may cap total requests per calendar month. Exceeding that returns 402 Payment Required, not 429, because it is a billing state rather than a pacing problem, waiting will not clear it until the month rolls over or the plan changes.

The edge limit behind those numbers

A limit in front of the application caps /api/tenant/ at 300 requests per minute per key, and it is not plan-aware. That is why no workspace plan is sold above 300: the plan and the edge are deliberately the same number, so the rate you are quoted is the rate you get.

If you need more than 300, ask support. It is provisioned for your workspace at the edge, not switched on in your console.

Recommended client behavior

1. Read retry_after_seconds from the 429 body and wait that long, rather than retrying immediately.
2. Use exponential backoff with jitter in automation.
3. Treat 402 differently from 429: do not retry a 402 on a backoff loop, it will not clear.
4. Monitor usage/quota dashboards for sustained high utilization.
5. Request a quota review when normal workload regularly approaches limits.