API Reference

Complete REST API documentation for RaSEC. All endpoints require authentication and return JSON responses.

Estimated reading time: 20 minutes

Overview

The RaSEC API provides programmatic access to all security testing tools and features. The API follows RESTful principles and uses JSON for request and response payloads.

API Version: All endpoints are currently unversioned. Future breaking changes will be introduced with versioned endpoints (e.g., /api/v2/).

Authentication

All API endpoints require authentication using Bearer tokens in the Authorization header.

API Tokens

API tokens provide programmatic access to RaSEC. Create tokens from Settings → API Tokens in the dashboard.

Authorization: <AUTH_HEADER>

Replace <AUTH_HEADER> with your Authorization header (Bearer scheme required).

Session Authentication

For browser-based requests, you can use session cookies from an authenticated session. This is automatically handled when making requests from the web application.

Security: Never expose API tokens in client-side code or public repositories. Tokens are only shown once when created. Store them securely.

Base URL

All API endpoints are relative to the base URL:

https://rasec.app/api

For local development: http://localhost:3000/api

Rate Limiting

API requests are rate-limited per organization to ensure fair usage and system stability. Rate limit information is included in response headers:

X-RateLimit-LimitMaximum requests per window

X-RateLimit-RemainingRemaining requests in current window

X-RateLimit-ResetUnix timestamp when limit resets

When rate limited, API returns 429 Too Many Requests status code.

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format:

400 Bad Request

Invalid request parameters or validation errors

{
  "error": "Validation failed",
  "details": {
    "fieldErrors": {
      "url": ["Invalid URL"]
    }
  }
}

401 Unauthorized

Missing or invalid authentication token

{
  "error": "Unauthorized",
  "message": "Invalid or missing API token"
}

403 Forbidden

Authenticated but lacks required permissions

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Server error occurred

Tool APIs

Tool APIs allow you to execute security testing tools programmatically. All tool endpoints require tools:run permission.

DAST Scanner

POST /api/tools/dast

Dynamic Application Security Testing. Analyzes web applications for vulnerabilities.

See DAST documentation for details.

SAST Analyzer

POST /api/tools/sast

Static Application Security Testing. Analyzes source code for security vulnerabilities.

See SAST documentation for details.

Security Headers

POST /api/tools/headers

Analyzes HTTP security headers (CSP, HSTS, X-Frame-Options, etc.).

Other Tools

Additional specialized tools available via API:

POST /api/tools/dom-xss - DOM XSS Pathfinder
POST /api/tools/jwt - JWT Analyzer
POST /api/tools/file-upload - File Upload Auditor
POST /api/tools/subdomain-finder - Subdomain Finder
POST /api/tools/url-finder - URL Finder
POST /api/tools/js-recon - JS Reconnaissance
POST /api/tools/payload-forge - Payload Forge
POST /api/tools/ssti-forge - SSTI Forge
POST /api/tools/oob-helper - OOB Interaction Helper
POST /api/tools/privesc - PrivEsc Pathfinder

Ingestion API

The Ingestion API allows you to upload security tool outputs (SARIF, Nuclei, ZAP, Burp) for automated parsing, deduplication, and integration into your security findings.

Upload Artifact

POST /api/ingestion/upload

Upload a security artifact file for processing. Supports multipart/form-data.

Supported Formats:

SARIF (.sarif, .json)
Nuclei (.json)
OWASP ZAP (.json, .xml)
Burp Suite (.json)

File Size Limit: 50MB

curl -X POST https://rasec.app/api/ingestion/upload \
  -H "<AUTH_HEADER>" \
  -F "file=@report.sarif"

Replace <AUTH_HEADER> with your Authorization header (Bearer scheme required).

Response:

{
  "jobId": "uuid",
  "status": "pending",
  "format": "sarif",
  "message": "Artifact uploaded successfully. Processing started."
}

Get Job Status

GET /api/ingestion/jobs/{jobId}

Get the status and results of an ingestion job.

Status Values:

pending - Job is queued for processing
processing - Job is currently being processed
completed - Job completed successfully
failed - Job failed with an error

Webhooks

Webhooks allow you to receive real-time notifications when events occur in RaSEC. Configure webhooks from Settings → Webhooks in the dashboard.

Webhook Events

finding.created - New vulnerability found
ingestion.completed - Ingestion job completed
ingestion.failed - Ingestion job failed
tool.run.completed - Tool execution completed

Webhook Security

Webhook payloads are signed with HMAC-SHA256 using a secret you configure. Verify signatures to ensure requests are from RaSEC.

X-RaSEC-Signature: sha256=signature_here
X-RaSEC-Timestamp: 1234567890

Retry Logic

Failed webhook deliveries are automatically retried with exponential backoff. Delivery history is available in the webhook management interface.

API Token Management

Create Token

POST /api/settings/api-tokens

Create a new API token. Tokens are only shown once when created.

List Tokens

GET /api/settings/api-tokens

List all API tokens for your organization. Token values are never returned.

Revoke Token

DELETE /api/settings/api-tokens/{tokenId}

Revoke an API token. Revoked tokens cannot be used for authentication.

Next Steps

Learn more about integrating RaSEC into your workflow:

Integrations

CI/CD integration and webhooks

Getting Started

Setup and first steps

API Reference

Complete REST API documentation for RaSEC. All endpoints require authentication and return JSON responses.

Estimated reading time: 20 minutes

Overview

The RaSEC API provides programmatic access to all security testing tools and features. The API follows RESTful principles and uses JSON for request and response payloads.

API Version: All endpoints are currently unversioned. Future breaking changes will be introduced with versioned endpoints (e.g., /api/v2/).

Authentication

All API endpoints require authentication using Bearer tokens in the Authorization header.

API Tokens

API tokens provide programmatic access to RaSEC. Create tokens from Settings → API Tokens in the dashboard.

Authorization: <AUTH_HEADER>

Replace <AUTH_HEADER> with your Authorization header (Bearer scheme required).

Session Authentication

For browser-based requests, you can use session cookies from an authenticated session. This is automatically handled when making requests from the web application.

Security: Never expose API tokens in client-side code or public repositories. Tokens are only shown once when created. Store them securely.

Base URL

All API endpoints are relative to the base URL:

https://rasec.app/api

For local development: http://localhost:3000/api

Rate Limiting

API requests are rate-limited per organization to ensure fair usage and system stability. Rate limit information is included in response headers:

X-RateLimit-LimitMaximum requests per window

X-RateLimit-RemainingRemaining requests in current window

X-RateLimit-ResetUnix timestamp when limit resets

When rate limited, API returns 429 Too Many Requests status code.

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format:

400 Bad Request

Invalid request parameters or validation errors

{
  "error": "Validation failed",
  "details": {
    "fieldErrors": {
      "url": ["Invalid URL"]
    }
  }
}

401 Unauthorized

Missing or invalid authentication token

{
  "error": "Unauthorized",
  "message": "Invalid or missing API token"
}

403 Forbidden

Authenticated but lacks required permissions

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Server error occurred

Tool APIs

Tool APIs allow you to execute security testing tools programmatically. All tool endpoints require tools:run permission.

DAST Scanner

POST /api/tools/dast

Dynamic Application Security Testing. Analyzes web applications for vulnerabilities.

See DAST documentation for details.

SAST Analyzer

POST /api/tools/sast

Static Application Security Testing. Analyzes source code for security vulnerabilities.

See SAST documentation for details.

Security Headers

POST /api/tools/headers

Analyzes HTTP security headers (CSP, HSTS, X-Frame-Options, etc.).

Other Tools

Additional specialized tools available via API:

POST /api/tools/dom-xss - DOM XSS Pathfinder
POST /api/tools/jwt - JWT Analyzer
POST /api/tools/file-upload - File Upload Auditor
POST /api/tools/subdomain-finder - Subdomain Finder
POST /api/tools/url-finder - URL Finder
POST /api/tools/js-recon - JS Reconnaissance
POST /api/tools/payload-forge - Payload Forge
POST /api/tools/ssti-forge - SSTI Forge
POST /api/tools/oob-helper - OOB Interaction Helper
POST /api/tools/privesc - PrivEsc Pathfinder

Ingestion API

The Ingestion API allows you to upload security tool outputs (SARIF, Nuclei, ZAP, Burp) for automated parsing, deduplication, and integration into your security findings.

Upload Artifact

POST /api/ingestion/upload

Upload a security artifact file for processing. Supports multipart/form-data.

Supported Formats:

SARIF (.sarif, .json)
Nuclei (.json)
OWASP ZAP (.json, .xml)
Burp Suite (.json)

File Size Limit: 50MB

curl -X POST https://rasec.app/api/ingestion/upload \
  -H "<AUTH_HEADER>" \
  -F "file=@report.sarif"

Replace <AUTH_HEADER> with your Authorization header (Bearer scheme required).

Response:

{
  "jobId": "uuid",
  "status": "pending",
  "format": "sarif",
  "message": "Artifact uploaded successfully. Processing started."
}

Get Job Status

GET /api/ingestion/jobs/{jobId}

Get the status and results of an ingestion job.

Status Values:

pending - Job is queued for processing
processing - Job is currently being processed
completed - Job completed successfully
failed - Job failed with an error

Webhooks

Webhooks allow you to receive real-time notifications when events occur in RaSEC. Configure webhooks from Settings → Webhooks in the dashboard.

Webhook Events

finding.created - New vulnerability found
ingestion.completed - Ingestion job completed
ingestion.failed - Ingestion job failed
tool.run.completed - Tool execution completed

Webhook Security

Webhook payloads are signed with HMAC-SHA256 using a secret you configure. Verify signatures to ensure requests are from RaSEC.

X-RaSEC-Signature: sha256=signature_here
X-RaSEC-Timestamp: 1234567890

Retry Logic

Failed webhook deliveries are automatically retried with exponential backoff. Delivery history is available in the webhook management interface.

API Token Management

Create Token

POST /api/settings/api-tokens

Create a new API token. Tokens are only shown once when created.

List Tokens

GET /api/settings/api-tokens

List all API tokens for your organization. Token values are never returned.

Revoke Token

DELETE /api/settings/api-tokens/{tokenId}

Revoke an API token. Revoked tokens cannot be used for authentication.

Next Steps

Learn more about integrating RaSEC into your workflow:

Integrations

CI/CD integration and webhooks

Getting Started

Setup and first steps

Table of Contents

Overview

Authentication

API Tokens

Session Authentication

Base URL

Rate Limiting

Error Handling

400 Bad Request

401 Unauthorized

403 Forbidden

429 Too Many Requests

500 Internal Server Error

Tool APIs

DAST Scanner

SAST Analyzer

Security Headers

Other Tools

Ingestion API

Upload Artifact

Get Job Status

Webhooks

Webhook Events

Webhook Security

Retry Logic

API Token Management

Create Token

List Tokens

Revoke Token

Next Steps

Integrations

Getting Started

Table of Contents

Overview

Authentication

API Tokens

Session Authentication

Base URL

Rate Limiting

Error Handling

400 Bad Request

401 Unauthorized

403 Forbidden

429 Too Many Requests

500 Internal Server Error

Tool APIs

DAST Scanner

SAST Analyzer

Security Headers

Other Tools

Ingestion API

Upload Artifact

Get Job Status

Webhooks

Webhook Events

Webhook Security

Retry Logic

API Token Management

Create Token

List Tokens

Revoke Token

Next Steps

Integrations

Getting Started