API access & tokens

BestDefense has a REST API you can call from scripts and pipelines to trigger scans, poll their progress, pull findings, kick off AI remediation, and run network scans. This page covers how to authenticate; see CI/CD automation for end-to-end pipeline examples.

Interactive reference

The complete, always-current API specification is built into the app at /api/docs (an interactive Swagger UI). Use it as the authoritative source for request and response schemas; this documentation covers the workflow and the endpoints most useful for automation.

Authentication

The API uses bearer tokens. Send your token in the Authorization header on every request:

Authorization: Bearer <your-token>

Tokens are organization-scoped — a token acts on behalf of one organization, and requests only ever see that organization’s data. (Requests for resources in another organization come back as 404 Not Found.)

Creating a token

1. In the app, go to Profile → API tokens (/profile/api-tokens). Accessing this page requires the manage integrations permission.
2. Create a token and give it a name.
3. Choose an expiration — between 1 and 90 days (default 30).
4. Save. The token is shown only once. Copy it immediately and store it somewhere safe — you can’t retrieve it again later.

You can list and revoke tokens from the same page. Revoking takes effect immediately.

Store tokens as secrets

A token is a credential for your organization. Store it in your CI/CD provider’s secret store (for example, GitHub Actions secrets or GitLab CI/CD variables) — never commit it to a repository or paste it into logs. Prefer a short expiration and rotate tokens regularly.

What a token can do

API actions are governed by your organization’s plan and allow-rules, the same way the app’s UI is. For example:

To…	Your organization needs…
Create a report (run a scan)	the create reports permission
Schedule a report	the manage scheduled reports permission and the appropriate plan
Trigger AI remediation	the AI remediation permission
Run a network scan	the run network scans permission
List/read scans and results	the relevant view permission

If your organization lacks a permission or your plan doesn’t include a feature, the API returns 403 Forbidden.

Response format

Most endpoints return a consistent envelope:

{
  "success": true,
  "message": "…",
  "data": {},
  "error": null
}

The data you want is under data. On errors, success is false and error describes the problem.

Note

A couple of endpoints deviate from this envelope. Notably, creating a report returns { "success": true, "message": "Report created.", "status": 200, "id": "<report-uuid>" } — the new report’s ID is at the top level, not under data.

Rate limits

The agent-distribution endpoints are rate-limited per token (the manifest at 60 requests/minute, the download at 20 requests/hour); exceeding a limit returns 429 Too Many Requests with a Retry-After header. Other endpoints aren’t rate limited today — but write your automation to handle 429 gracefully regardless.

Next steps

• CI/CD automation — a worked pipeline that triggers a scan, waits for it, and fails the build on high-severity findings.
• The interactive spec at /api/docs for full request/response schemas.