ASTRA BASTION - AI Security & Governance

API Reference

Complete REST API documentation for all 12 modules. ~239 verified endpoints with JSON envelope responses, cursor-based pagination, and RFC 7807 error handling.

Base URL

All API requests are made relative to the base URL:

https://api.astrabastion.com/api/v1

Self-hosted deployments use your configured domain. All endpoints require HTTPS in production.

Authentication

ASTRA BASTION uses JWT Bearer tokens for authentication. Include the token in the Authorization header of every request.

http

"text-purple-400 font-bold">GET /api/v1/trust/scores/current
"text-cyan-400">Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
"text-cyan-400">Content-Type: application/json
"text-cyan-400">X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000

JWT Token Structure

json

{
  "sub": "user-uuid-v7",
  "tid": "tenant-uuid-v7",
  "role": "security_admin",
  "permissions": ["gateway:read", "gateway:write", "trust:read"],
  "iat": 1710500000,
  "exp": 1710503600
}

Tokens expire after 1 hour. Use the refresh endpoint POST /api/v1/auth/refresh to obtain a new access token without re-authenticating.

Request & Response Format

All responses use a standard JSON envelope with data, meta, and errors fields.

json

{
  "data": {
    "id": "01913a5c-7e4d-7d3a-8b1c-0242ac130003",
    "trust_score": 87.5,
    "grade": "B+",
    "pillars": {
      "security": 91.2,
      "compliance": 85.0,
      "risk": 82.3,
      "resilience": 88.7,
      "ai_governance": 90.1
    }
  },
  "meta": {
    "request_id": "req_01913a5c8f2a",
    "timestamp": "2026-03-15T10: 30: 00Z",
    "version": "v1"
  },
  "errors": null
}

Pagination

List endpoints use cursor-based pagination for consistent performance at any scale. Pass the cursor from the previous response to fetch the next page.

json

{
  "data": [ ... ],
  "meta": {
    "pagination": {
      "cursor": "eyJpZCI6IjAxOTEzYTVjLTdlNGQifQ==",
      "limit": 25,
      "has_more": true,
      "total_count": 142
    }
  }
}

Request: GET /api/v1/iam/users?limit=25&cursor=eyJpZCI6...

Rate Limiting

API requests are rate-limited per tenant using a Redis sliding window algorithm. Check the response headers to monitor your usage.

Header	Description	Example
X-RateLimit-Limit	Max requests per window	1000
X-RateLimit-Remaining	Remaining requests in window	847
X-RateLimit-Reset	Unix timestamp when window resets	1710503600

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header indicating seconds to wait.

Error Format

All errors follow RFC 7807 Problem Details with additional ASTRA-specific fields.

json

{
  "type": "https://api.astrabastion.com/errors/GW-003",
  "title": "Prompt Injection Detected",
  "status": 422,
  "detail": "The input prompt matched 3 injection patterns: role-override, instruction-leak, delimiter-attack. Request blocked by gateway policy.",
  "instance": "/api/v1/gateway/chat/completions",
  "error_code": "GW-003",
  "request_id": "req_01913a5c8f2a",
  "timestamp": "2026-03-15T10: 30: 00Z"
}

HTTP Status Codes

200 -- Success
201 -- Created
400 -- Validation error
401 -- Unauthorized
403 -- Forbidden
404 -- Not found

409 -- Conflict
422 -- Unprocessable (domain error)
429 -- Rate limited
500 -- Internal error
502 -- Upstream provider error
503 -- Service unavailable

Module Endpoints

Module	Path Prefix	Endpoints	Resources
IAM	/api/v1/iam	~35	Users, roles, sessions, API keys, tenants, SSO
Gateway	/api/v1/gateway	~40	Providers, policies, requests, kill switch, cache
Trust	/api/v1/trust	~10	Scores, pillars, history, decay configuration
AEGIS	/api/v1/aegis	~47	Agents, guardrails, MCP firewall, Shadow AI, alerts
Compliance	/api/v1/compliance	~13	Frameworks, assessments, controls, evidence
Risk	/api/v1/risk	~11	Risk register, FAIR analysis, Monte Carlo, threats
Resilience	/api/v1/resilience	~11	Scenarios, simulations, RTO/RPO, chaos injection
BASTION AI	/api/v1/bastion-ai	~15	Chat, RAG queries, provider management, context
Platform	/api/v1/platform	~15	Notifications, reports, workflows, integrations
Admin	/api/v1/admin	~20	System config, feature flags, health, licenses
CyberTwins	/api/v1/cybertwins	~10	Assets, graphs, attack paths, campaigns
Data Gov	/api/v1/data-gov	~12	Classification, DSAR, lineage, retention policies

POST/api/v1/auth/login

Authenticate with email and password to receive a JWT access token and refresh token.

Request

json

{
  "email": "admin@enterprise.com",
  "password": "••••••••••••",
  "mfa_code": "482901"
}

Response (200 OK)

json

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": {
      "id": "01913a5c-7e4d-7d3a-8b1c-0242ac130003",
      "email": "admin@enterprise.com",
      "role": "security_admin",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  },
  "meta": {
    "request_id": "req_01913a5c8f2a",
    "timestamp": "2026-03-15T10: 30: 00Z"
  }
}

Example: AI Gateway Chat

POST/api/v1/gateway/chat/completions

Proxy an LLM chat completion through ASTRA's 14-step security pipeline. Supports OpenAI-compatible format with automatic prompt injection detection, PII redaction, and audit logging.

Request

json

{
  "provider": "openai",
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a financial analyst assistant." },
    { "role": "user", "content": "Summarize Q4 earnings for AAPL." }
  ],
  "temperature": 0.7,
  "max_tokens": 2048,
  "policy_id": "01913a5c-prod-policy"
}

Response (200 OK)

json

{
  "data": {
    "id": "chatcmpl-01913a5c9f3b",
    "model": "gpt-4o",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Apple reported Q4 FY2025 revenue of..."
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 42,
      "completion_tokens": 318,
      "total_tokens": 360
    },
    "security": {
      "injection_score": 0.02,
      "pii_detected": false,
      "policy_violations": [],
      "pipeline_latency_ms": 23
    }
  }
}

Example: Trust Score

GET/api/v1/trust/scores/current

Retrieve the current composite trust score for your tenant, including individual pillar breakdowns and grade.

Response (200 OK)

json

{
  "data": {
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
    "composite_score": 87.5,
    "grade": "B+",
    "pillars": {
      "security": { "score": 91.2, "weight": 0.25, "source": "aegis" },
      "compliance": { "score": 85.0, "weight": 0.25, "source": "compliance" },
      "risk": { "score": 82.3, "weight": 0.20, "source": "risk" },
      "resilience": { "score": 88.7, "weight": 0.15, "source": "resilience" },
      "ai_governance": { "score": 90.1, "weight": 0.15, "source": "gateway" }
    },
    "trend": "+2.3",
    "last_recalculated_at": "2026-03-15T10: 28: 00Z",
    "decay_model": "exponential"
  }
}

WebSocket API

Subscribe to real-time events via WebSocket for live dashboards, alerting, and streaming AI responses.

typescript

// Connect to WebSocket
const ws = new WebSocket('wss://api.astrabastion.com/ws');
// Authenticate
ws.send(JSON.stringify({
  type: 'authenticate',
  token: 'eyJhbGciOiJSUzI1NiIs...'
}));
// Subscribe to events
ws.send(JSON.stringify({
  type: 'subscribe',
  channels: [
    'trust.score.updated',
    'gateway.request.blocked',
    'aegis.agent.anomaly',
    'aegis.kill_switch.activated'
  ]
}));
// Handle events
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // CloudEvents v1.0 envelope
  // msg.type = "com.astra.trust.ScoreUpdated"
  // msg.data = { tenant_id, score, grade, ... }
};

Available Channels

trust.score.updated

gateway.request.completed

gateway.request.blocked

aegis.agent.anomaly

aegis.kill_switch.activated

compliance.assessment.completed

risk.score.changed

platform.notification.created

SDK Examples

Python

python

"text-purple-400">from astra_bastion "text-purple-400">import AstraBastion
client = AstraBastion(
    api_key="ab_live_...",
    base_url="https://api.astrabastion.com"
)
# Proxy a chat completion
response = "text-purple-400">await client.gateway.chat(
    provider="openai",
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Hello"}
    ],
    policy_id="prod-policy-001"
)
# Check trust score
score = "text-purple-400">await client.trust.get_current_score()
print(f"Trust: {score.composite} ({score.grade})")

TypeScript

typescript

import { AstraBastion } from '@astra-bastion/sdk'
const client = new AstraBastion({
  apiKey: 'ab_live_...',
  baseUrl: 'https://api.astrabastion.com'
})
// Proxy a chat completion
const response = await client.gateway.chat({
  provider: 'openai',
  model: 'gpt-4o',
  messages: [
    { role: 'user', content: 'Hello' }
  ],
  policyId: 'prod-policy-001'
})
// Check trust score
const score = await client.trust.getCurrentScore()
console.log(`Trust: ${score.composite} (${score.grade})`)

API Reference

Base URL

Authentication

JWT Token Structure

Request & Response Format

Pagination

Rate Limiting

Error Format

HTTP Status Codes

Module Endpoints

Example: Authentication

Request

Response (200 OK)

Example: AI Gateway Chat

Request

Response (200 OK)

Example: Trust Score

Response (200 OK)

WebSocket API

Available Channels

SDK Examples

Python

TypeScript