TrigGuard API Reference

BASE URL https://api.trigguardai.com

OPENAPI SPECIFICATION Machine-readable API contract for tooling and SDK generation

POST /execute

Request authorization for an irreversible action. Returns a deterministic decision and a cryptographically signed receipt.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer $TG_API_KEY

Request Body

Parameter	Type	Description
surfacerequired	string	Authorization surface identifier (e.g., "deploy.release", "infra.terraform", "data.export")
actionoptional	string	Specific action within the surface (e.g., "promote-to-production")
actoroptional	string	Identity of the executing actor (e.g. agent.billing, support-agent, human-admin). Enables policy by who is executing; use with tool-call shape.
contextoptional	object	Contextual metadata for policy evaluation (commit, branch, environment, actor, etc.)
idempotency_keyoptional	string	Unique key for idempotent requests. Same key returns same receipt.

Example Request

CURL

curl -X POST https://api.trigguardai.com/execute \
  -H "Authorization: Bearer $TG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "surface": "deploy.release",
    "action": "promote-to-production",
    "context": {
      "commit": "a1b2c3d4",
      "branch": "main",
      "environment": "production",
      "actor": "ci-bot"
    },
    "idempotency_key": "deploy-2026-03-13-001"
  }'

Response — PERMIT

200 OK

{
  "decision": "PERMIT",
  "enforcement": "EXECUTED",
  "receipt_id": "tg_rcpt_7f3a9c2b1d4e5f6a",
  "timestamp": "2026-03-13T14:22:00.000Z",
  "expires_at": "2026-03-13T14:32:00.000Z",
  "signature": "ed25519:rWqYsX8HjK2mN...",
  "key_id": "tg_key_2026_03"
}

Response — DENY

403 FORBIDDEN

{
  "decision": "DENY",
  "enforcement": "BLOCKED",
  "reason_code": "POLICY_VIOLATION",
  "policy_id": "prod-deploy-hours",
  "message": "Production deploys refused outside business hours",
  "receipt_id": "tg_rcpt_8e4b2a1c3d5f6e7a",
  "signature": "ed25519:pL7mKx9RtN3..."
}

Response — SILENCE

422 UNPROCESSABLE

{
  "decision": "SILENCE",
  "enforcement": "BLOCKED",
  "reason_code": "INDETERMINATE_EVALUATION",
  "message": "Cannot evaluate: missing required context field 'environment'",
  "receipt_id": "tg_rcpt_9f5c3b2a1d4e6f7b"
}

Decision Types

Decision	HTTP Status	Meaning
PERMIT	200	Action is authorized. Proceed with execution. Receipt valid for specified TTL.
DENY	403	Action is denied. Reason and policy ID included. Do not proceed.
SILENCE	422	System cannot evaluate. Insufficient context or policy conflict. Fail-closed.

Response Fields

Field	Type	Description
decision	string	One of: PERMIT, DENY, SILENCE
receipt_id	string	Unique receipt identifier. Format: tg_rcpt_{16 hex chars}
timestamp	string	ISO 8601 timestamp of decision
expires_at	string	Receipt expiration time (PERMIT only)
signature	string	Ed25519 signature. Format: ed25519:{base64}
key_id	string	Signing key identifier for verification
reason	string	Reason code (DENY/SILENCE only)
policy_id	string	Violated policy identifier (DENY only)
message	string	Human-readable explanation (DENY/SILENCE only)

GET /.well-known/trigguard-keys.json

Retrieve public keys for offline receipt verification. Keys are rotated periodically. Multiple keys may be active during rotation.

Authentication

No authentication required. This is a public endpoint.

Example Request

CURL

curl https://api.trigguardai.com/.well-known/trigguard-keys.json

Response

200 OK

{
  "keys": [
    {
      "key_id": "tg_key_2026_03",
      "algorithm": "ed25519",
      "public_key": "MCowBQYDK2VwAyEA...",
      "created_at": "2026-03-01T00:00:00.000Z",
      "expires_at": "2026-06-01T00:00:00.000Z",
      "status": "active"
    },
    {
      "key_id": "tg_key_2026_02",
      "algorithm": "ed25519",
      "public_key": "MCowBQYDK2VwAyEA...",
      "created_at": "2026-02-01T00:00:00.000Z",
      "expires_at": "2026-05-01T00:00:00.000Z",
      "status": "active"
    }
  ],
  "issuer": "https://api.trigguardai.com",
  "cache_ttl": 3600
}

Key Fields

Field	Type	Description
key_id	string	Unique key identifier. Referenced in receipt signatures.
algorithm	string	Signing algorithm. Currently only "ed25519".
public_key	string	Base64-encoded public key in SubjectPublicKeyInfo format.
created_at	string	Key creation timestamp.
expires_at	string	Key expiration timestamp. Do not verify receipts signed after this time.
status	string	Key status: "active" or "revoked".

Caching

The cache_ttl field indicates how long (in seconds) keys can be cached. Recommended: cache keys locally and refresh periodically.

// ERROR HANDLING

Error Responses

Status	Code	Description
400	invalid_request	Malformed request body or missing required fields
401	unauthorized	Invalid or missing API key
403	forbidden	API key lacks permission for this surface
404	surface_not_found	Unknown authorization surface
429	rate_limited	Too many requests. Check Retry-After header.
500	internal_error	Internal server error. Request should be retried.
503	service_unavailable	Service temporarily unavailable. Check status page.

Error Response Format

ERROR RESPONSE

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: surface",
    "request_id": "req_8f3a2b1c4d5e6f7a"
  }
}