API Reference Overview¶

The ARX REST API provides programmatic access to all platform capabilities: agent management, connector operations, policy configuration, audit trail queries, approval workflows, and compliance package generation. This page covers authentication, request and response conventions, pagination, error handling, rate limiting, and RBAC requirements.

Base URL¶

All API requests are made to:

https://api.arxsec.io

API paths are versioned. The current version is v1. A full endpoint URL follows the pattern:

https://api.arxsec.io/v1/{resource}

For self-hosted or staging environments, the base URL is configured per deployment. The SDK accepts this via the ARXSEC_API_URL environment variable or the api_url constructor parameter.

Authentication¶

The API supports two authentication methods. Every request must include exactly one.

Bearer JWT Token¶

Used by the ARX console and integrations that authenticate through Supabase Auth, Auth0 SAML, or OIDC. Include the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

The API accepts JWTs issued by:

• Supabase Auth -- Verified with HS256 using the Supabase anon key. Audience: authenticated.
• Auth0 (SAML/OIDC) -- Verified with RS256 using the Auth0 JWKS endpoint. Audience: configured per tenant.

JWT tokens carry the user identity, organization, and role. Tokens expire according to the issuer's configuration. Expired tokens return a 401 Unauthorized response.

API Key¶

Used by the SDK, CI/CD pipelines, and server-to-server integrations. Include the key in the X-API-Key header:

X-API-Key: arx_sk_your_api_key_here

Alternatively, the SDK sends the API key as a Bearer token in the Authorization header:

Authorization: Bearer arx_sk_your_api_key_here

API keys are scoped to the user who created them and inherit that user's organization and role. Keys can have an expiration date. Keys are stored as SHA-256 hashes -- ARX does not retain the plaintext key after creation.

To create an API key:

curl -X POST "https://api.arxsec.io/v1/api-keys" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "triage-agent-prod",
    "role": "deployer",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

The response includes the key value once. Store it securely.

Request Format¶

All request bodies use JSON. Set the Content-Type header:

Content-Type: application/json

Query parameters are used for filtering, pagination, and sorting on GET requests. Request body JSON is used for POST, PUT, PATCH, and DELETE requests.

SDK Execute Endpoint¶

The primary endpoint for agent operations:

POST /v1/sdk/execute

Request body:

{
  "connector": "crowdstrike",
  "operation": "detections:read",
  "params": {
    "limit": 10,
    "filter": "status:'new'"
  },
  "session_context": {
    "prior_actions": [
      {"connector": "crowdstrike", "operation": "detections:read"}
    ]
  }
}

The session_context field is optional. The SDK populates it automatically with the last 100 actions from the current session.

Response Format¶

All responses use a consistent JSON envelope:

Success Response¶

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-11T14:30:00Z"
  }
}

For list endpoints, the data field contains an array and meta includes pagination information:

{
  "data": [ ... ],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-11T14:30:00Z",
    "total": 247,
    "limit": 50,
    "offset": 0
  }
}

Error Response¶

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Operation hosts:write denied by policy rule pol_xyz789",
    "details": {
      "connector": "crowdstrike",
      "operation": "hosts:write",
      "verdict": "DENY",
      "policy_id": "pol_xyz789"
    }
  },
  "meta": {
    "request_id": "req_def456",
    "timestamp": "2026-04-11T14:30:01Z"
  }
}

Pagination¶

List endpoints support limit and offset query parameters:

Example:

GET /v1/audit?connector=crowdstrike&limit=100&offset=200

The meta.total field in the response indicates the total number of matching records. Use offset + limit to iterate through all pages.

Error Codes¶

The API uses standard HTTP status codes with structured error bodies.

Mapping Policy Verdicts to HTTP Status Codes¶

Rate Limiting¶

The API enforces per-organization rate limits. Rate limit status is communicated via response headers on every request:

Default rate limits:

If your agent exceeds the rate limit, implement exponential backoff with jitter. The SDK does not retry automatically on 429 responses.

RBAC Role Requirements¶

Every API endpoint requires a minimum RBAC role. The authenticated user's role is checked before the request is processed. If the user's role is insufficient, the API returns 403 Forbidden with a message indicating the required roles.

The require_role decorator is applied to every route handler. It extracts the authenticated user from the request context and checks their role against the endpoint's allowed roles list.

Request IDs¶

Every API response includes a request_id in the meta object. Include this ID when contacting support for troubleshooting. Request IDs are also logged in the server-side audit trail, enabling end-to-end tracing from client request to connector execution.

TLS and Network Security¶

All API communication requires TLS 1.2 or later. Plaintext HTTP requests are rejected. Organizations can configure IP allowlisting to restrict API access to approved CIDR ranges. IP allowlists are enforced at the network edge before authentication.

SDK vs. Direct API¶

The ARX SDK is the recommended interface for agent code. It handles authentication header construction, session context tracking, and HTTP client lifecycle management. Use the REST API directly for:

• CI/CD pipeline integrations
• Custom dashboards and reporting tools
• Webhook handlers that respond to ARX events
• Languages without an official SDK

All SDK operations ultimately call the same REST API endpoints documented here.