Security Events API

STACK automatically monitors your organization for security anomalies and generates events when suspicious activity is detected. The Security Events API lets you list, inspect, and resolve these events. All endpoints require authentication via the Authorization: Bearer sk_live_... header.

Security events require operator-level access. Team member API keys cannot access these endpoints and will receive 403 Forbidden. Only the operator's master API key or a valid session JWT can be used.

List Security Events

Retrieve unresolved security events for your organization, with optional filtering by agent and pagination.

bash

# List unresolved events (default)
curl "https://api.getstack.run/v1/security-events?page=1&limit=50" \
  -H "Authorization: Bearer sk_live_your_key"

# Filter by agent
curl "https://api.getstack.run/v1/security-events?agent_id=agt_xyz&limit=20" \
  -H "Authorization: Bearer sk_live_your_key"

Query Parameters

agent_id (string, optional) — filter events by a specific agent ID
page (integer, optional) — page number, default 1 (1-indexed)
limit (integer, optional) — events per page, default 50, max 100

Response

json

{
  "events": [
    {
      "id": "sev_abc123",
      "operator_id": "op_xyz",
      "agent_id": "agt_xyz",
      "passport_jti": "jti_abc",
      "signal_type": "credential_burst",
      "severity": "warning",
      "message": "Agent retrieved 15 credentials within 30 seconds",
      "metadata": {
        "credential_count": 15,
        "time_window_seconds": 30
      },
      "resolved": false,
      "resolved_at": null,
      "created_at": "2026-04-15T10:05:00Z"
    },
    {
      "id": "sev_def456",
      "operator_id": "op_xyz",
      "agent_id": "agt_abc",
      "passport_jti": "jti_def",
      "signal_type": "credential_outside_scope",
      "severity": "critical",
      "message": "Proxy request for notion not in passport scope",
      "metadata": {
        "intent_services": ["slack", "github"],
        "granted_providers": ["slack", "github"]
      },
      "resolved": false,
      "resolved_at": null,
      "created_at": "2026-04-15T09:30:00Z"
    }
  ],
  "unresolved_count": 7,
  "page": 1,
  "limit": 50
}

The unresolved_count field reflects the total number of unresolved events across your entire organization, regardless of pagination or agent filter. Use this to power badge counts in your UI.

Get a Security Event

Retrieve full details for a specific security event by ID.

bash

curl https://api.getstack.run/v1/security-events/sev_abc123 \
  -H "Authorization: Bearer sk_live_your_key"

Returns 404 if the event does not exist or belongs to a different operator.

Signal Types

STACK detects and categorizes security events into the following signal types, each with an associated severity level.

credential_outside_scope

An agent attempted to access a credential or proxy a request for a service that is not listed in the passport's scope. In enforced mode this blocks the request; in logged mode the request proceeds but the event is recorded.

Severity: critical (enforced mode) or warning (logged mode)
Metadata: intent_services, granted_providers

credential_after_checkout

An agent attempted to access a credential or use the proxy after the passport has been checked out. This is always blocked regardless of accountability mode.

Severity: critical
Metadata: service name, passport JTI

credential_burst

An agent retrieved an unusually high number of credentials in a short time window, which may indicate credential exfiltration.

Severity: warning or critical depending on volume
Metadata: credential_count, time_window_seconds

delegation_without_intent

A passport delegation was created without a matching intent declaration.

Severity: warning

delegation_downgrade

A delegated passport was issued with broader scope than the parent passport. Delegation should only narrow scope.

Severity: critical

checkpoint_silence

An agent failed to report a checkpoint within the expected interval.

Severity: warning

expired_no_checkout

A passport expired without ever being checked out, which may indicate an agent that abandoned a task without proper cleanup.

Severity: info

scope_escalation_pattern

An agent is systematically requesting passports with increasingly broader scopes, potentially probing for access.

Severity: warning or critical

credential_unreported

An agent accessed credentials during a passport session but did not report them in the checkout. This signal is generated by comparing Redis-tracked credential access against the checkout report.

Severity: warning
Metadata: accessed services, reported services

Severity Levels

Every security event has one of three severity levels:

info — informational, no immediate action required (e.g., expired_no_checkout)
warning — suspicious pattern detected, should be reviewed (e.g., credential_burst, credential_unreported)
critical — active security threat, requires immediate investigation (e.g., credential_outside_scope in enforced mode, credential_after_checkout)

Automatic Agent Blocking

When a critical-severity event is recorded, STACK checks the agent's on_critical configuration. If set to block, the agent is automatically blocked from receiving new passports. The agent's passport_blocked flag is set to true with a reason message.

Resolve a Security Event

Mark a security event as resolved after investigation. The resolve endpoint takes no request body.

bash

curl -X POST https://api.getstack.run/v1/security-events/sev_abc123/resolve \
  -H "Authorization: Bearer sk_live_your_key"

json

{
  "resolved": true,
  "id": "sev_abc123"
}

Returns 404 if the event does not exist or belongs to a different operator.

Once resolved, an event cannot be re-opened. If the same anomaly recurs, STACK generates a new event automatically.

Automated Response

Security events integrate with the Notifications API. Configure notification rules to get alerts when events are generated.

bash

# Alert on all critical security events
curl -X POST https://api.getstack.run/v1/notifications/rules \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "security.event",
    "destinations": ["dm_slack_channel", "dm_oncall_email"],
    "conditions": {
      "severity": "critical"
    }
  }'

For programmatic response, configure a webhook delivery method and implement automated remediation. For example, automatically revoking all passports for an agent when a credential_outside_scope event fires.

Best Practices

Set up notification rules for security.event before going to production
Use webhook delivery with a Slack or PagerDuty integration for critical events
Review and resolve open events regularly
Monitor unresolved_count as a key metric in your observability stack
Configure on_critical: "block" on agents that handle sensitive data
Use enforced accountability mode on passports for highest security