The JSON API

The web app is a client of the same public API you can use. There is no private endpoint that does something the API cannot, and no way to reach another organization’s data through it. The base path is /api/v1, every body is JSON, timestamps are UTC ISO-8601, and every response carries an x-request-id header that error bodies repeat.

Authentication

• Send Authorization: Bearer <accessToken>. Access tokens are short-lived JWTs (fifteen minutes).
• Refresh tokens are opaque and rotate on every use; reusing a rotated token revokes the whole session family.
• Accounts with two-factor authentication get an mfaRequired challenge from /auth/login and finish it at /auth/mfa.

Tenancy and permissions

• Send X-Organization-Id: org_… when you belong to more than one organization. With exactly one, it is implied.
• Roles are OWNER, ADMIN, MEMBER and VIEWER over 18 permissions; each endpoint declares the one it needs, printed in the tables that follow.
• Tenant identity never travels in a body. A resource in another organization answers 404, not 403.

Errors

{
  "error": {
    "code": "SITE_NOT_FOUND",
    "message": "Site not found",
    "requestId": "req_…",
    "details": {}
  }
}

Codes are stable: VALIDATION_ERROR, UNAUTHENTICATED, FORBIDDEN, NOT_A_MEMBER, ORGANIZATION_CONTEXT_REQUIRED, INSUFFICIENT_PERMISSION, RATE_LIMITED, SITE_NOT_FOUND, SITE_LIMIT_REACHED, SCAN_COOLDOWN, TOO_MANY_ACTIVE_SCANS, FREE_SCAN_ALLOWANCE_REACHED, FINDING_NOT_FOUND, INVALID_STATE_TRANSITION and a few more, each named in the endpoint that raises it.

Pagination

List endpoints take limit (default 25, at most 100) and cursor, and return { items, nextCursor }. Ordering is newest first with the id as a tiebreaker, so a page never repeats or skips a row while new ones arrive. Filters are explicit allowlists.

curl https://api.appscan.sh/api/v1/sites \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Organization-Id: org_…"