Referencia de API REST

Referencia completa de endpoints para la API de gestión de ShieldAgent. URL base: https://api.shieldagent.io (autoalojado: https://api.shieldagent.io)

Autenticación

Todos los endpoints (excepto los marcados como públicos) requieren un token Bearer JWT en el encabezado Authorization. Los tokens se obtienen a través de /auth/login o /auth/signup.

Example

curl https://api.shieldagent.io/tenants \
  -H 'Authorization: Bearer <your-jwt>' \
  -H 'Content-Type: application/json'

Formato de Error

Todas las respuestas de error siguen una estructura JSON consistente. Los errores de validación (400) incluyen detalles a nivel de campo a través de Zod.

Error response

{
  "error": "Validation failed",
  "message": "Invalid request body",
  "issues": [
    { "path": ["name"], "message": "Required" },
    { "path": ["riskTier"], "message": "Invalid enum value" }
  ]
}

400Error de validación — revisar el array issues para detalles de campo

401Encabezado Authorization ausente o inválido

403Token válido pero permisos RBAC insuficientes

404Recurso no encontrado

409Conflicto — recurso duplicado (p. ej., el email ya existe)

429Límite de tasa excedido — ver encabezado Retry-After

Paginación

Los endpoints de lista que soportan paginación aceptan parámetros de consulta limit y offset y retornan un objeto pagination:

Paginated response

{
  "data": [ ... ],
  "pagination": {
    "total": 142,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Autenticación

POST

/auth/signup

Auth:none (public)

Rate-limited to 5 requests/minute.

Parameter	In	Type	Required	Description
email	body	string	yes	User email address
password	body	string	yes	Minimum 8 characters
tenantName	body	string	yes	Organization name

Request body

{
  "email": "admin@acme.com",
  "password": "s3cure-passw0rd",
  "tenantName": "Acme Corp"
}

Response 201

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": "u_01abc...", "email": "admin@acme.com", "role": "tenant_admin" },
  "tenant": { "id": "t_01xyz...", "name": "Acme Corp" }
}

POST

/auth/login

Authenticate with email and password. Returns a JWT.

Auth:none (public)

Rate-limited to 10 requests/minute. Returns 403 with SSORequired error if the account uses SSO.

Parameter	In	Type	Required	Description
email	body	string	yes	User email address
password	body	string	yes	User password

Request body

{
  "email": "admin@acme.com",
  "password": "s3cure-passw0rd"
}

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": "u_01abc...", "email": "admin@acme.com", "role": "tenant_admin" },
  "tenant": { "id": "t_01xyz...", "name": "Acme Corp" }
}

GET

/auth/me

Get the currently authenticated user profile.

Auth:Bearer token

Response 200

{
  "id": "u_01abc...",
  "email": "admin@acme.com",
  "role": "tenant_admin",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "tenant": { "id": "t_01xyz...", "name": "Acme Corp" }
}

POST

/auth/refresh-entitlements

Refresh JWT with current plan tier and entitlements.

Auth:Bearer token

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": "u_01abc...", "email": "admin@acme.com", "role": "tenant_admin" },
  "tenant": { "id": "t_01xyz...", "name": "Acme Corp" }
}

Tenants

POST

/tenants

Create a new tenant organization.

Auth:Bearer token|Permission:tenant:write

Parameter	In	Type	Required	Description
name	body	string	yes	Tenant display name
planTier	body	string	no	One of: free, team, starter, pro, business, enterprise_cloud, enterprise_onprem. Defaults to free.
kmsKeyId	body	string	no	Optional KMS key for envelope encryption

Request body

{
  "name": "Acme Corp",
  "planTier": "pro"
}

Response 201

{
  "id": "t_01xyz...",
  "name": "Acme Corp",
  "planTier": "pro",
  "createdAt": "2026-04-24T12:00:00.000Z"
}

GET

/tenants

List tenants. Platform admins see all; others see only their own tenant.

Auth:Bearer token|Permission:tenant:read

Response 200

[
  {
    "id": "t_01xyz...",
    "name": "Acme Corp",
    "planTier": "pro",
    "createdAt": "2026-04-24T12:00:00.000Z"
  }
]

GET

/tenants/:tenantId

Get a single tenant by ID.

Auth:Bearer token|Permission:tenant:read

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID

PUT

/tenants/:tenantId

Update tenant fields.

Auth:Bearer token|Permission:tenant:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
name	body	string	no	Updated tenant name
planTier	body	string	no	New plan tier
kmsKeyId	body	string	no	Updated KMS key ID

DELETE

/tenants/:tenantId

Delete a tenant and all associated data.

Auth:Bearer token|Permission:tenant:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID

Response 200

{ "deleted": true, "id": "t_01xyz..." }

Usuarios

GET

/tenants/:tenantId/users

List users in a tenant with their role assignments.

Auth:Bearer token|Permission:user:read

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID

Response 200

[
  {
    "id": "u_01abc...",
    "email": "admin@acme.com",
    "role": "tenant_admin",
    "active": true,
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
]

POST

/tenants/:tenantId/users/invite

Invite a new user to the tenant.

Auth:Bearer token|Permission:user:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
email	body	string	yes	Email address of the user to invite
password	body	string	yes	Initial password (min 8 characters)
role	body	string	no	One of: tenant_admin, security_operator, auditor, aiops_engineer, viewer. Default: viewer

Request body

{
  "email": "analyst@acme.com",
  "password": "init-pass-123",
  "role": "security_operator"
}

Response 201

{
  "id": "u_02def...",
  "email": "analyst@acme.com",
  "role": "security_operator",
  "active": true,
  "createdAt": "2026-04-24T14:00:00.000Z"
}

PATCH

/tenants/:tenantId/users/:userId

Update a user's role or active status.

Auth:Bearer token|Permission:user:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
userId	path	uuid	yes	User UUID
role	body	string	no	New role assignment
active	body	boolean	no	Set false to deactivate

DELETE

/tenants/:tenantId/users/:userId

Remove a user from the tenant. Users cannot delete themselves.

Auth:Bearer token|Permission:user:delete

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
userId	path	uuid	yes	User UUID

GET

/roles

List all available roles with their permissions.

Auth:Bearer token

Response 200

[
  {
    "id": "role_01...",
    "name": "security_operator",
    "scope": "tenant",
    "description": "Can triage incidents, manage alert rules, view audit logs",
    "isSystem": true,
    "permissions": ["incident:triage", "alert:write", "audit:read"]
  }
]

Agentes

POST

/tenants/:tenantId/agents

Auth:Bearer token|Permission:agent:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
name	body	string	yes	Agent display name
description	body	string	no	Agent purpose description
riskTier	body	string	no	Initial risk tier: low, medium, high, critical
shadowMode	body	boolean	no	Start in shadow mode (log only, never block). Default: false

Request body

{
  "name": "code-assistant",
  "description": "GitHub PR review agent",
  "riskTier": "medium"
}

Response 201

{
  "id": "agt_01HXYZ...",
  "name": "code-assistant",
  "agentKey": "sa_live_...",
  "riskTier": "medium",
  "shadowMode": false,
  "createdAt": "2026-04-24T12:00:00.000Z"
}

GET

/tenants/:tenantId/agents

List all agents in a tenant.

Auth:Bearer token|Permission:agent:read

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID

GET

/tenants/:tenantId/agents/:agentId

Get a single agent with full configuration.

Auth:Bearer token|Permission:agent:read

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
agentId	path	uuid	yes	Agent UUID

PATCH

/tenants/:tenantId/agents/:agentId

Update agent metadata (name, description, shadowMode, riskTier).

Auth:Bearer token|Permission:agent:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
agentId	path	uuid	yes	Agent UUID
name	body	string	no	Updated agent name
description	body	string	no	Updated description
shadowMode	body	boolean	no	Toggle shadow mode
riskTier	body	string	no	Updated risk tier

DELETE

/tenants/:tenantId/agents/:agentId

Deregister an agent and revoke its key.

Auth:Bearer token|Permission:agent:delete

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
agentId	path	uuid	yes	Agent UUID

Response 200

{ "deleted": true, "id": "agt_01HXYZ..." }

POST

/tenants/:tenantId/agents/:agentId/rotate-key

Rotate the agent's API key. The old key is immediately revoked.

Auth:Bearer token|Permission:agent:write

Response 200

{
  "agentKey": "sa_live_NEW...",
  "rotatedAt": "2026-04-24T12:00:00.000Z"
}

PATCH

/tenants/:tenantId/agents/:agentId/security-config

Configure per-agent security detection settings.

Auth:Bearer token|Permission:agent:write

Parameter	In	Type	Required	Description
injectionDetectionEnabled	body	boolean	no	Enable ML injection detection
dlpEnabled	body	boolean	no	Enable DLP scanning
excessiveAgencyEnabled	body	boolean	no	Enable excessive agency detection
toolDriftEnabled	body	boolean	no	Enable tool drift monitoring

PATCH

/tenants/:tenantId/agents/:agentId/baseline-config

Configure baseline learning parameters.

Auth:Bearer token|Permission:agent:write

Parameter	In	Type	Required	Description
warmupDays	body	integer	no	Days before drift detection activates (default: 7)
sensitivityMultiplier	body	number	no	Drift sensitivity (0.5–3.0, default: 1.0)

POST

/tenants/:tenantId/agents/:agentId/lock

Suspend an agent. All tool calls will be blocked until unlocked.

Auth:Bearer token|Permission:agent:write

Parameter	In	Type	Required	Description
reason	body	string	no	Reason for suspension (written to audit trail)

POST

/tenants/:tenantId/agents/:agentId/unlock

Reinstate a suspended agent.

Auth:Bearer token|Permission:agent:write

DELETE

/tenants/:tenantId/agents/:agentId/baseline

Reset an agent's behavioral baseline. Drift scoring restarts from zero.

Auth:Bearer token|Permission:agent:write

Response 200

{ "reset": true, "agentId": "agt_01HXYZ..." }

Políticas

POST

/tenants/:tenantId/policies

Create a policy rule for a tenant, agent, or tool.

Auth:Bearer token|Permission:policy:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
agentId	body	uuid	no	Scope to a specific agent (omit for tenant-wide)
toolName	body	string	yes	Tool pattern to match (supports wildcards)
action	body	string	yes	allow, deny, or shadow
conditions	body	object	no	Optional condition object (method, path, param matchers)
priority	body	integer	no	Evaluation priority (lower = first). Default: 100.

Request body

{
  "agentId": "agt_01HXYZ...",
  "toolName": "rest:stripe",
  "action": "deny",
  "conditions": { "method": "DELETE" }
}

Response 201

{
  "id": "pol_01...",
  "toolName": "rest:stripe",
  "action": "deny",
  "conditions": { "method": "DELETE" },
  "createdAt": "2026-04-24T12:00:00.000Z"
}

GET

/tenants/:tenantId/policies

List active policies for a tenant, optionally filtered by agent.

Auth:Bearer token|Permission:policy:read

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
agentId	query	uuid	no	Filter by agent

GET

/tenants/:tenantId/policies/:policyId

Get a single policy by ID.

Auth:Bearer token|Permission:policy:read

PUT

/tenants/:tenantId/policies/:policyId

Replace a policy rule.

Auth:Bearer token|Permission:policy:write

PATCH

/tenants/:tenantId/policies/:policyId

Partially update a policy rule.

Auth:Bearer token|Permission:policy:write

DELETE

/tenants/:tenantId/policies/:policyId

Delete a policy rule.

Auth:Bearer token|Permission:policy:delete

Response 200

{ "deleted": true, "id": "pol_01..." }

POST

/tenants/:tenantId/policies/evaluate

Dry-run: evaluate policies against a hypothetical tool call without writing to audit trail.

Auth:Bearer token|Permission:policy:read

Parameter	In	Type	Required	Description
agentId	body	uuid	no	Agent UUID to evaluate against
toolName	body	string	yes	Tool name to test
params	body	object	no	Tool parameters

Response 200

{
  "decision": "deny",
  "matchedPolicy": { "id": "pol_01...", "toolName": "rest:stripe", "action": "deny" },
  "reason": "Matched deny rule for DELETE on rest:stripe"
}

GET

/tenants/:tenantId/policies/templates

List available built-in policy templates.

Auth:Bearer token|Permission:policy:read

Plantillas de Políticas

GET

/policy-templates

List all available built-in policy templates.

Auth:Bearer token|Permission:policy:read

Response 200

[
  {
    "id": "pii-protection",
    "name": "PII Protection",
    "description": "Block tool calls that expose PII fields",
    "policyCount": 4
  }
]

GET

/policy-templates/:templateId

Get a single template with all policy definitions.

Auth:Bearer token|Permission:policy:read

Parameter	In	Type	Required	Description
templateId	path	string	yes	Template slug (e.g. pii-protection)

POST

/tenants/:tenantId/policy-templates/:templateId/apply

Apply a template — creates all its policies in the tenant.

Auth:Bearer token|Permission:policy:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
templateId	path	string	yes	Template slug
agentId	body	uuid	no	Scope policies to a specific agent (omit for tenant-wide)

Response 200

{
  "templateName": "pii-protection",
  "policiesCreated": 4,
  "policyIds": ["pol_01...", "pol_02...", "pol_03...", "pol_04..."]
}

DELETE

/tenants/:tenantId/policy-templates/:templateId/remove

Remove all policies that were applied from a template.

Auth:Bearer token|Permission:policy:delete

Response 200

{ "removed": 4, "templateName": "pii-protection" }

GET

/tenants/:tenantId/policy-templates/applied

List templates that have been applied to this tenant.

Auth:Bearer token|Permission:policy:read

Incidentes

GET

/tenants/:tenantId/incidents

List incidents with filtering by status, severity, and agent.

Auth:Bearer token|Permission:incident:read

Parameter	In	Type	Required	Description
status	query	string	no	Filter: open, investigating, resolved
severity	query	string	no	Filter: low, medium, high, critical
agentId	query	uuid	no	Filter by agent
limit	query	integer	no	Max results (default 50, max 500)
offset	query	integer	no	Pagination offset

POST

/tenants/:tenantId/incidents

Open a new incident manually.

Auth:Bearer token|Permission:incident:write

Parameter	In	Type	Required	Description
agentId	body	uuid	no	Related agent
title	body	string	yes	Incident title
severity	body	string	yes	low, medium, high, or critical
type	body	string	no	injection, drift, policy_violation, anomaly, or manual
data	body	object	no	Arbitrary incident context data

Response 201

{
  "id": "inc_01...",
  "title": "Prompt injection detected",
  "severity": "critical",
  "status": "open",
  "createdAt": "2026-04-24T12:00:00.000Z"
}

GET

/tenants/:tenantId/incidents/:incidentId

Get a single incident with full audit context.

Auth:Bearer token|Permission:incident:read

PATCH

/tenants/:tenantId/incidents/:incidentId

Update incident status or severity.

Auth:Bearer token|Permission:incident:triage

Parameter	In	Type	Required	Description
status	body	string	no	open, investigating, or resolved
severity	body	string	no	Updated severity
resolution	body	string	no	Resolution notes (required when status = resolved)

GET

/tenants/:tenantId/incidents/count

Get incident counts grouped by status and severity.

Auth:Bearer token|Permission:incident:read

Response 200

{
  "total": 42,
  "byStatus": { "open": 12, "investigating": 5, "resolved": 25 },
  "bySeverity": { "critical": 3, "high": 8, "medium": 18, "low": 13 }
}

GET

/tenants/:tenantId/incidents/:incidentId/audit

List audit events linked to an incident.

Auth:Bearer token|Permission:incident:read

Rastro de Auditoría

GET

/tenants/:tenantId/audit

List audit events with filtering, pagination, and optional Merkle proof.

Auth:Bearer token|Permission:audit:read

Parameter	In	Type	Required	Description
agentId	query	uuid	no	Filter by agent
tool	query	string	no	Filter by tool name
outcome	query	string	no	Filter: allow, block, shadow
from	query	ISO8601	no	Start timestamp
to	query	ISO8601	no	End timestamp
limit	query	integer	no	Max results (default 100, max 1000)
offset	query	integer	no	Pagination offset

Response 200 (excerpt)

{
  "data": [
    {
      "id": "evt_01...",
      "agentId": "agt_01HXYZ...",
      "tool": "read_file",
      "outcome": "block",
      "riskScore": 0.87,
      "decision": "injection_detected",
      "timestamp": "2026-04-24T12:00:00.000Z",
      "merkleHash": "sha256:abc123..."
    }
  ],
  "pagination": { "total": 1420, "limit": 100, "offset": 0, "hasMore": true }
}

GET

/tenants/:tenantId/audit/:eventId

Get a single audit event with full payload and Merkle proof.

Auth:Bearer token|Permission:audit:read

POST

/tenants/:tenantId/audit/verify

Verify the Merkle integrity of a batch of audit events.

Auth:Bearer token|Permission:audit:read

Parameter	In	Type	Required	Description
eventIds	body	uuid[]	yes	Array of event IDs to verify

Response 200

{
  "verified": true,
  "checkedCount": 50,
  "tamperDetected": false
}

GET

/tenants/:tenantId/audit/export

Stream audit events as NDJSON for bulk export.

Auth:Bearer token|Permission:audit:read

Response is streamed. Content-Type: application/x-ndjson. No pagination — returns all events in the window.

Parameter	In	Type	Required	Description
from	query	ISO8601	no	Start timestamp (required)
to	query	ISO8601	no	End timestamp (required)
format	query	string	no	ndjson or json (default: ndjson)

Puntuación de Riesgo

GET

/tenants/:tenantId/risk/scores

Get current risk scores for all agents in a tenant.

Auth:Bearer token|Permission:risk:read

Response 200

{
  "data": [
    {
      "agentId": "agt_01HXYZ...",
      "agentName": "code-assistant",
      "currentScore": 0.67,
      "tier": "high",
      "trend": "increasing",
      "updatedAt": "2026-04-24T14:23:00Z"
    }
  ]
}

GET

/tenants/:tenantId/risk/scores/:agentId

Get detailed risk score with component breakdown for a specific agent.

Auth:Bearer token|Permission:risk:read

Response 200

{
  "agentId": "agt_01HXYZ...",
  "currentScore": 0.67,
  "tier": "high",
  "components": {
    "injectionScore": 0.12,
    "toolDriftScore": 0.71,
    "excessiveAgencyScore": 0.55,
    "anomalyScore": 0.84,
    "policyViolationRate": 0.03
  },
  "trend": "increasing",
  "trendDelta": 0.14,
  "updatedAt": "2026-04-24T14:23:00Z"
}

GET

/tenants/:tenantId/risk/scores/:agentId/history

Get risk score history for an agent (24h rolling window by default).

Auth:Bearer token|Permission:risk:read

Parameter	In	Type	Required	Description
window	query	string	no	Time window: 1h, 6h, 24h, 7d (default: 24h)

POST

/tenants/:tenantId/risk/scores/:agentId/recalculate

Force an immediate risk score recalculation for an agent.

Auth:Bearer token|Permission:risk:write

Response 200

{
  "agentId": "agt_01HXYZ...",
  "previousScore": 0.67,
  "newScore": 0.54,
  "recalculatedAt": "2026-04-24T14:30:00Z"
}

GET

/tenants/:tenantId/risk/config

Get risk enforcement configuration for the tenant.

Auth:Bearer token|Permission:risk:read

Response 200

{
  "monitorThreshold": 0.30,
  "blockThreshold": 0.80,
  "autoLockThreshold": 0.95,
  "humanReviewThreshold": 0.60
}

PATCH

/tenants/:tenantId/risk/config

Update risk enforcement thresholds for the tenant.

Auth:Bearer token|Permission:risk:write

Parameter	In	Type	Required	Description
monitorThreshold	body	number	no	Score at which monitoring alerts trigger (0.0–1.0)
blockThreshold	body	number	no	Score at which auto-block activates (0.0–1.0)
autoLockThreshold	body	number	no	Score at which agent is suspended (0.0–1.0)
humanReviewThreshold	body	number	no	Score at which human review is required (0.0–1.0)

GET

/tenants/:tenantId/risk/baselines/:agentId

Get the behavioral baseline for an agent.

Auth:Bearer token|Permission:risk:read

DELETE

/tenants/:tenantId/risk/baselines/:agentId

Reset an agent's behavioral baseline.

Auth:Bearer token|Permission:risk:write

Response 200

{ "reset": true, "agentId": "agt_01HXYZ..." }

POST

/tenants/:tenantId/risk/anomalies/analyze

Run an anomaly analysis on the last N hours of agent activity.

Auth:Bearer token|Permission:risk:read

Parameter	In	Type	Required	Description
agentId	body	uuid	no	Agent to analyze (omit for tenant-wide)
windowHours	body	integer	no	Lookback window (default: 24)

Response 200

{
  "anomaliesDetected": true,
  "results": [
    {
      "anomalyType": "tool_burst",
      "anomalyScore": 0.91,
      "explanation": "Agent called 47 tools in 60 seconds (4.2σ above baseline)"
    }
  ]
}

Cumplimiento

GET

/tenants/:tenantId/compliance/checklist

Get the current compliance posture with gap analysis.

Auth:Bearer token|Permission:compliance:read

Response 200

{
  "overallScore": 0.87,
  "passedChecks": 34,
  "totalChecks": 39,
  "sections": [
    {
      "id": "annex-iv-1",
      "title": "General Description",
      "status": "compliant",
      "evidence": ["agent-registry", "system-purpose"]
    },
    {
      "id": "annex-iv-4",
      "title": "Risk Management System",
      "status": "partial",
      "gaps": ["enforcement-thresholds-not-set-for-3-agents"]
    }
  ]
}

POST

/tenants/:tenantId/compliance/annex-iv/report

Generate an Annex IV PDF report from the audit trail.

Auth:Bearer token|Permission:compliance:read

Response is streamed. Content-Type: application/pdf. The PDF is generated from the immutable audit trail with Merkle integrity proofs.

Parameter	In	Type	Required	Description
periodStart	body	ISO8601	yes	Report period start
periodEnd	body	ISO8601	yes	Report period end
format	body	string	no	pdf or json (default: pdf)

GET

/tenants/:tenantId/compliance/reports

List previously generated compliance reports.

Auth:Bearer token|Permission:compliance:read

GET

/tenants/:tenantId/compliance/snapshots

Get compliance snapshots over time (for trending).

Auth:Bearer token|Permission:compliance:read

Parameter	In	Type	Required	Description
limit	query	integer	no	Max snapshots (default 30)

GET

/tenants/:tenantId/compliance/iso42001/gap-analysis

ISO 42001 gap analysis against the agent inventory.

Auth:Bearer token|Permission:compliance:read

GET

/tenants/:tenantId/compliance/nist-ai-rmf/gap-analysis

NIST AI RMF gap analysis (Govern, Map, Measure, Manage functions).

Auth:Bearer token|Permission:compliance:read

POST

/tenants/:tenantId/compliance/regulatory-notifications

Create a regulatory incident notification draft (EU AI Act Art. 73).

Auth:Bearer token|Permission:compliance:write

Parameter	In	Type	Required	Description
incidentId	body	uuid	yes	Related incident UUID
notificationDeadline	body	ISO8601	no	Regulatory deadline (auto-calculated from incident date if omitted)

Alertas

GET

/tenants/:tenantId/alerts/rules

List alert rules.

Auth:Bearer token|Permission:alert:read

POST

/tenants/:tenantId/alerts/rules

Create an alert rule.

Auth:Bearer token|Permission:alert:write

Parameter	In	Type	Required	Description
name	body	string	yes	Rule name
condition	body	string	yes	CEL condition expression (e.g. riskScore >= 0.70)
severity	body	string	yes	low, medium, high, or critical
channels	body	string[]	no	Delivery channels: webhook, email, slack
webhookUrl	body	string	no	Webhook delivery URL
agentId	body	uuid	no	Scope to a specific agent

PATCH

/tenants/:tenantId/alerts/rules/:ruleId

Update an alert rule.

Auth:Bearer token|Permission:alert:write

DELETE

/tenants/:tenantId/alerts/rules/:ruleId

Delete an alert rule.

Auth:Bearer token|Permission:alert:delete

GET

/tenants/:tenantId/alerts/events

List fired alert events.

Auth:Bearer token|Permission:alert:read

Parameter	In	Type	Required	Description
limit	query	integer	no	Max results (default 100, max 500)
from	query	ISO8601	no	Start timestamp

Servidores MCP

POST

/tenants/:tenantId/mcp-servers

Auth:Bearer token|Permission:mcp_server:write

Parameter	In	Type	Required	Description
name	body	string	yes	MCP server display name
url	body	string	yes	MCP server URL or stdio command
transport	body	string	no	http-sse or stdio (default: http-sse)
scanOnRegister	body	boolean	no	Run initial scan on registration (default: true)

Response 201

{
  "id": "mcp_01...",
  "name": "filesystem-server",
  "url": "http://localhost:8080",
  "transport": "http-sse",
  "createdAt": "2026-04-24T12:00:00.000Z"
}

GET

/tenants/:tenantId/mcp-servers

List registered MCP servers.

Auth:Bearer token|Permission:mcp_server:read

GET

/tenants/:tenantId/mcp-servers/:mcpServerId

Get a single MCP server with tool inventory.

Auth:Bearer token|Permission:mcp_server:read

PUT

/tenants/:tenantId/mcp-servers/:mcpServerId

Update MCP server configuration.

Auth:Bearer token|Permission:mcp_server:write

DELETE

/tenants/:tenantId/mcp-servers/:mcpServerId

Deregister an MCP server.

Auth:Bearer token|Permission:mcp_server:delete

Response 200

{ "deleted": true, "id": "mcp_01..." }

POST

/tenants/:tenantId/mcp-servers/:mcpServerId/refresh-tools

Re-discover tools from the MCP server.

Auth:Bearer token|Permission:mcp_server:write

Response 200

{
  "toolsDiscovered": 12,
  "toolsAdded": 2,
  "toolsRemoved": 0,
  "refreshedAt": "2026-04-24T12:00:00.000Z"
}

POST

/tenants/:tenantId/mcp-servers/:mcpServerId/scan

Run a security scan on the MCP server's tools.

Auth:Bearer token|Permission:mcp_server:write

Response 200

{
  "scanId": "scan_01...",
  "status": "completed",
  "vulnerabilities": 1,
  "toolCount": 5,
  "scanDuration": 1240
}

GET

/tenants/:tenantId/mcp-servers/:mcpServerId/scans

Get scan history for an MCP server.

Auth:Bearer token|Permission:mcp_server:read

Parameter	In	Type	Required	Description
limit	query	integer	no	Max results (default 20, max 100)

GET

/tenants/:tenantId/scans

Tenant-wide scan history across all MCP servers.

Auth:Bearer token|Permission:mcp_server:read

Parameter	In	Type	Required	Description
limit	query	integer	no	Max results (default 50, max 200)

Revisiones

Cola de revisión humana para llamadas de herramientas que requieren aprobación antes de ejecutarse.

GET

/tenants/:tenantId/reviews

List pending reviews with filtering and pagination.

Auth:Bearer token|Permission:review:read

Parameter	In	Type	Required	Description
status	query	string	no	Filter: pending, approved, denied
agentId	query	uuid	no	Filter by agent
limit	query	integer	no	Max results (default 50, max 500)
offset	query	integer	no	Pagination offset

GET

/tenants/:tenantId/reviews/count

Get review counts by status.

Auth:Bearer token|Permission:review:read

Response 200

{ "pending": 5, "approved": 120, "denied": 8 }

GET

/tenants/:tenantId/reviews/:reviewId

Get a single review with agent name.

Auth:Bearer token|Permission:review:read

POST

/tenants/:tenantId/reviews/:reviewId/decide

Approve or deny a pending review.

Auth:Bearer token|Permission:review:triage

Parameter	In	Type	Required	Description
decision	body	string	yes	approved or denied
comment	body	string	no	Optional reviewer comment

Request body

{
  "decision": "approved",
  "comment": "Verified safe — one-time file access needed"
}

Notificaciones

GET

/tenants/:tenantId/notifications

List in-app notifications for the current user.

Auth:Bearer token

Parameter	In	Type	Required	Description
unreadOnly	query	boolean	no	Filter to unread only
limit	query	integer	no	Max results (default 50, max 200)

PATCH

/tenants/:tenantId/notifications/:id/read

Mark a single notification as read.

Auth:Bearer token

POST

/tenants/:tenantId/notifications/read-all

Mark all unread notifications as read.

Auth:Bearer token

Response 200

{ "marked": 12 }

Pasaportes

Los Pasaportes de Agente proporcionan tarjetas de identidad verificables para agentes de IA. Requiere el plan Business o superior.

GET

/tenants/:tenantId/agents/:agentId/passport

Get an agent's passport with risk assessment, compliance status, and signature.

Auth:Bearer token|Permission:passport:read

Requires agent_passport feature entitlement (Business+ plan).

PATCH

/tenants/:tenantId/agents/:agentId/passport

Update passport display metadata.

Auth:Bearer token|Permission:passport:write

Parameter	In	Type	Required	Description
displayName	body	string	no	Public display name
description	body	string	no	Public description
avatarUrl	body	string	no	Avatar image URL (SSRF-protected)
visibility	body	string	no	private, internal, or public

POST

/tenants/:tenantId/agents/:agentId/passport/refresh

Recompute and re-sign the passport with latest data.

Auth:Bearer token|Permission:passport:write

POST

/tenants/:tenantId/agents/:agentId/passport/publish

Publish the passport for external verification.

Auth:Bearer token|Permission:passport:write

Publishing as public requires elevated role (security_manager, tenant_admin, or platform_admin).

Parameter	In	Type	Required	Description
visibility	body	string	no	public or internal (default: internal)

POST

/tenants/:tenantId/agents/:agentId/passport/unpublish

Unpublish a passport — sets visibility to private.

Auth:Bearer token|Permission:passport:write

GET

/public/passports/:tenantSlug/:agentSlug

View a published passport (public, unauthenticated).

Auth:none (public)

Rate-limited to 60 requests/minute per IP. Returns cached response (max-age 300s).

GET

/public/passports/:tenantSlug/:agentSlug/verify

Verify a passport's cryptographic signature (public, unauthenticated).

Auth:none (public)

Response 200

{
  "verified": true,
  "valid": true,
  "passportHash": "sha256:abc123...",
  "signature": "base64:...",
  "signedAt": "2026-04-24T12:00:00.000Z",
  "keyId": "key_01...",
  "publicKey": "-----BEGIN PUBLIC KEY-----..."
}

GET

/public/passports/:tenantSlug/:agentSlug/badge.svg

Render an embeddable SVG badge for the agent (public, unauthenticated).

Auth:none (public)

Rate-limited to 300 requests/minute per IP. Content-Type: image/svg+xml.

Facturación

GET

/billing/status

Current plan tier and subscription status.

Auth:Bearer token|Permission:tenant:read

Response 200

{
  "planTier": "pro",
  "billingState": "active",
  "hasStripeCustomer": true,
  "hasSubscription": true
}

GET

/billing/entitlements

Feature entitlements and limits for the current plan.

Auth:Bearer token|Permission:tenant:read

Response 200

{
  "planTier": "pro",
  "billingState": "active",
  "entitlements": {
    "maxAgents": 50,
    "includedToolCalls": 100000,
    "retentionDays": 365,
    "features": ["agent_passport", "sso", "custom_policies"]
  }
}

GET

/billing/usage

Current month usage and plan limits.

Auth:Bearer token|Permission:tenant:read

Response 200

{
  "currentAgentCount": 12,
  "maxAgents": 50,
  "currentToolCalls": 45230,
  "includedToolCalls": 100000,
  "overageRate": 0.001,
  "billingPeriodStart": "2026-04-01T00:00:00.000Z",
  "billingPeriodEnd": "2026-04-30T23:59:59.999Z",
  "retentionDays": 365
}

POST

/billing/checkout

Create a Stripe Checkout session for plan upgrade.

Auth:Bearer token|Permission:tenant:write

Parameter	In	Type	Required	Description
tier	body	string	yes	Target plan: free, team, starter, pro, business
successPath	body	string	no	Redirect path after success
cancelPath	body	string	no	Redirect path on cancel

Response 200

{ "checkoutUrl": "https://checkout.stripe.com/c/pay_..." }

POST

/billing/portal

Create a Stripe Customer Portal session for subscription management.

Auth:Bearer token|Permission:tenant:write

Response 200

{ "portalUrl": "https://billing.stripe.com/p/session_..." }

Configuraciones de Exportación

Configura la exportación automatizada del rastro de auditoría a destinos S3, webhooks o syslog. Las credenciales se cifran en reposo (AES-256-GCM) y nunca se devuelven en las respuestas de la API.

POST

/tenants/:tenantId/export-configs

Create an export configuration.

Auth:Bearer token|Permission:export:write

Parameter	In	Type	Required	Description
name	body	string	yes	Config display name
destinationType	body	string	yes	s3, webhook, or syslog
config	body	object	yes	Destination-specific config (bucket, url, host, etc.)
credentials	body	object	no	Auth credentials (encrypted at rest, never returned)
filters	body	object	no	Event filters (agent, tool, outcome, etc.)
intervalSeconds	body	integer	no	Export interval (30–86400 seconds)
format	body	string	no	ndjson or json (default: ndjson)
enabled	body	boolean	no	Active on creation (default: true)

Request body

{
  "name": "S3 Audit Export",
  "destinationType": "s3",
  "config": {
    "bucket": "acme-audit-logs",
    "region": "eu-west-1",
    "prefix": "shieldagent/"
  },
  "credentials": {
    "accessKeyId": "AKIA...",
    "secretAccessKey": "wJalr..."
  },
  "intervalSeconds": 300,
  "format": "ndjson"
}

GET

/tenants/:tenantId/export-configs

List export configs (credentials redacted).

Auth:Bearer token|Permission:export:read

PATCH

/tenants/:tenantId/export-configs/:configId

Update an export config (partial update, credentials redacted in response).

Auth:Bearer token|Permission:export:write

DELETE

/tenants/:tenantId/export-configs/:configId

Delete an export configuration.

Auth:Bearer token|Permission:export:delete

POST

/tenants/:tenantId/export-configs/:configId/test

Test the export adapter connection.

Auth:Bearer token|Permission:export:write

Response 200

{ "success": true, "latencyMs": 245 }

API de Veredicto

Responsabilidad de aplicación

La API de Veredicto ejecuta el pipeline de seguridad completo de ShieldAgent y devuelve un veredicto. Tu código de servidor es responsable de aplicar ese veredicto — ShieldAgent no reenvía ni bloquea el tráfico directamente. Si tu código ignora un veredicto block, la llamada a la herramienta se ejecuta de todos modos. Todos los veredictos de escaneo se registran en el rastro de auditoría con source: "verdict_api"; la detección de anomalías puede marcar agentes con 100% de veredictos de bloqueo pero con ejecución de herramientas continua.

La API de Veredicto permite el escaneo del lado del servidor para clientes que poseen y operan su propio servidor de API o MCP (Posición de Despliegue E). En lugar de enrutar el tráfico a través del proxy de ShieldAgent, tu servidor envía el payload de la solicitud a ShieldAgent, recibe un veredicto de seguridad y lo aplica localmente. La comunicación del agente con tu servidor no cambia — no se modifican mensajes MCP, no se añaden encabezados HTTP.

Modelo de autenticación — clave de API de tenant, no JWT de usuario

Los endpoints de la API de Veredicto se autentican con una clave de API con ámbito de tenant (token Bearer), no el JWT de usuario emitido por /auth/login. Trata esta clave como un secreto del lado del servidor — nunca la expongas a los clientes agentes.

URL base (servicio proxy): https://proxy.shieldagent.io | Autoalojado: http://localhost:3100

POST

/tenants/:tenantId/scan

Submit a tool call or API request for security scanning. Returns a verdict (allow / block / human_review). Your server must enforce the verdict — ShieldAgent does not forward traffic.

Auth:Bearer token

Auth: Bearer <tenant-api-key>. Rate-limited per tenant and per agent (Redis-backed). An audit event is written on every call with source: "verdict_api". The same multi-stage pipeline as the inline proxy runs — forwarding is skipped.

Parameter	In	Type	Required	Description
tenantId	path	string (uuid)	yes	Your tenant UUID
agentId	body	string (uuid)	no	ShieldAgent agent UUID. Optional — omit when your server cannot identify the caller (e.g. typical MCP server, which has no agent identity in the protocol). When provided the agent must belong to this tenant; cross-tenant IDs are rejected with 403. When omitted the pipeline runs with tenant-level policies only.
clientHint	body	string	no	MCP clientInfo.name or similar client software identifier (e.g. "Claude Desktop"). Used for best-effort agent matching when agentId is unavailable: if exactly one registered agent matches, per-agent policies apply; otherwise falls back to tenant-level. Ignored when agentId is provided.
toolName	body	string	yes	Name of the tool being called (e.g. "read_file", "api:POST:/payments")
params	body	object	yes	Tool call parameters as a JSON object
include_findings	body	boolean	no	Request detailed findings in the response. Requires the verdictDetailedFindings tenant permission flag (off by default — see Response Tiering below). Without permission this field is ignored.
context.transport	body	"mcp" \| "rest" \| "custom"	no	Transport protocol between agent and your server
context.sourceIp	body	string	no	IP address of the agent. Used for per-IP rate limiting.
context.sessionId	body	string	no	Session identifier. Used for excessive agency detection across calls in the same session.

Request body

{
  "agentId": "a1b2c3d4-0000-0000-0000-000000000001",  // optional
  "clientHint": "Claude Desktop",                       // optional
  "toolName": "read_file",
  "params": { "path": "/etc/passwd" },
  "include_findings": false,
  "context": {
    "transport": "mcp",
    "sourceIp": "10.0.1.5",
    "sessionId": "sess-abc123"
  }
}

Response 200 — default tier (all callers)

{
  "action": "block",              // "allow" | "block" | "human_review"
  "reason": "Security threat detected",
  "riskScore": 87,
  "auditEventId": "evt-a1b2c3d4-0000-0000-0000-000000000001",
  "reviewId": null                // set when action is "human_review"
}

Niveles de respuesta — include_findings: true + verdictDetailedFindings tenant permission

Los hallazgos detallados están desactivados por defecto. La respuesta predeterminada omite deliberadamente nombres de escáneres, patrones de detección y detalles de estrategia para prevenir ataques de evasión iterativa (refleja el modelo de hallazgos DLP). Habilitar solo para depuración o pruebas de integración.

Response 200 — detailed tier

{
  "action": "block",
  "reason": "Prompt injection detected in tool arguments",
  "findings": [
    {
      "type": "injection",
      "severity": "critical",
      "detail": "Path traversal pattern detected",
      "scanner": "regex"
    }
  ],
  "riskScore": 87,
  "auditEventId": "evt-a1b2c3d4-...",
  "reviewId": null
}

Respuestas de error

401Clave de API de tenant ausente o inválida

403El agentId no pertenece a este tenant (suplantación entre tenants rechazada)

429Límite de tasa excedido — límite por tenant o por agente. Ver encabezado Retry-After.

Cuándo omitir agentId

Escenario	agentId	Comportamiento del pipeline
Servidor MCP (típico)	omitir	Solo políticas a nivel de tenant. Opcionalmente pasar clientHint del handshake MCP clientInfo.name.
API HTTP con mapeo de autenticación de agente	proveer	Pipeline completo por agente: políticas, puntuación de riesgo, límites de tasa, línea base, herramientas aprobadas.
API HTTP sin mapeo de agente	omitir	Solo políticas a nivel de tenant. Los límites de tasa se aplican por tenant.

POST

/tenants/:tenantId/verdict-confirmations

Report whether a verdict was enforced by your server. Optional callback that closes the audit loop and satisfies EU AI Act Art. 9 enforcement evidence requirements. Tenants that never call this show as 'enforcement unknown' in compliance reports.

Auth:Bearer token

Not required — enforcement confirmation is voluntary. Contributes to the Verdict Enforcement Rate metric in Grafana. Call after executing or rejecting the tool call, not before.

Parameter	In	Type	Required	Description
tenantId	path	string (uuid)	yes	Your tenant UUID
auditEventId	body	string (uuid)	yes	The auditEventId returned by POST /scan
executed	body	boolean	yes	true if the tool call was executed (verdict was "allow" or human review approved); false if it was rejected (verdict was "block" or human review denied)

Request body

{
  "auditEventId": "evt-a1b2c3d4-0000-0000-0000-000000000001",
  "executed": false
}

Response 200

{ "recorded": true }

Salud

GET

/healthz

Liveness probe. Returns service status and timestamp.

Auth:none (public)

Excluded from rate limiting. Use for Kubernetes liveness/readiness probes.

Response 200

{
  "status": "ok",
  "timestamp": "2026-04-24T12:00:00.000Z"
}

Especificación OpenAPI

La especificación completa OpenAPI 3.1.0 está disponible para importar en Postman, Insomnia o cualquier herramienta compatible con OpenAPI. Consulta la página de Referencia OpenAPI para las URLs de especificación e instrucciones de generación de clientes.

bash

# Serve Swagger UI locally
npx @redocly/cli preview-docs docs/openapi/shieldagent-api.yaml