> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Kill Switch
> Emergency kill switch: immediately revoke an agent, terminate all sessions, and void pending receipts.
Activates the emergency kill switch for an agent. This is a destructive, irreversible operation that immediately:
1. **Revokes the agent** -- sets the agent status to `revoked`, preventing all future API calls
2. **Terminates all active sessions** -- forcibly ends every session associated with the agent
3. **Voids pending receipts** -- marks all unfinalized receipts as voided to prevent downstream reliance on incomplete data
The kill switch is designed for critical security incidents where an agent must be immediately neutralized -- such as confirmed credential compromise, detected malicious behavior, or regulatory emergency shutdown orders.
**Irreversible Operation.** Agent revocation via kill switch cannot be undone.
A new agent must be registered to resume operations. All voided receipts are
permanently marked and cannot be restored.
### Audit Trail
The kill switch activation generates a `killswitch.activated` event with full details, a transparency-log receipt anchoring the revocation, and notifications to all configured webhook endpoints and SIEM integrations.
### Authentication
API key with `agents:kill` scope. This is a privileged scope typically
restricted to security team keys. Alternatively, pass a Bearer JWT token with
the `security-admin` role.
Tenant identifier for multi-tenant isolation.
### Path Parameters
Agent identifier to kill (e.g. `maip-agent:01HXYZ9A1B2C3D4E5F`).
### Request
Mandatory explanation for the kill switch activation. Recorded in the audit
trail and included in all notifications.
Identifier of the human operator or automated system that initiated the kill.
If omitted, the API key identity is used.
### Response
The revoked agent identifier.
Agent status after kill switch: `revoked`.
Number of active sessions that were forcibly terminated.
Number of pending receipts that were voided.
The reason provided for the kill switch activation.
The operator who initiated the kill.
Transparency-log receipt anchoring the kill switch event.
ISO 8601 timestamp of the kill switch activation.
## OpenAPI
````yaml mint-openapi.yaml POST /v1/agents/{agentId}/kill
openapi: 3.0.3
info:
title: Truthlocks API
description: >
Truthlocks is a universal verification infrastructure for documents,
credentials, and digital assets.
This specification defines the canonical API for interacting with Truthlocks
services.
## Base URLs
- **Production**: `https://api.truthlocks.com`
- **Sandbox**: `https://sandbox-api.truthlocks.com`
## Authentication
- **API Keys**: Use `X-API-Key` header for machine-to-machine operations
- **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated
operations
## Tenant Identity
In production, tenant identity is derived from the authenticated context
(API key or JWT).
The `X-Tenant-ID` header is ignored in production to prevent spoofing.
version: 1.0.0
contact:
name: Truthlocks Support
url: https://truthlocks.com/support
email: support@truthlocks.com
servers:
- url: https://api.truthlocks.com
description: Production API
- url: https://sandbox-api.truthlocks.com
description: Sandbox Environment
security:
- APIKey: []
tags:
- name: Authentication
description: API key and token management
- name: Issuers
description: Issuer registration and trust management
- name: Keys
description: Cryptographic key management for issuers
- name: Attestations
description: Attestation lifecycle (mint, revoke, supersede)
- name: Verification
description: Attestation verification and proof bundles
- name: Governance
description: Issuer governance workflows (admin only)
- name: Identity
description: Organization, user, and role management
- name: Audit
description: Audit event queries
- name: Platform
description: Platform administration (super admin only)
- name: Platform Review
description: Staff review workflows for issuer applications
- name: Tenant Console
description: Tenant profile and lifecycle endpoints
- name: Health
description: Service health and readiness endpoints
- name: Risk
description: Risk signal ingestion and fraud detection
- name: Risk Enforcement
description: Risk enforcement actions — block, challenge, quarantine, and configuration
- name: Billing
description: Billing, subscription, and addon management
- name: Machine Identity
description: >-
Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
trust, witness, compliance, orchestration, and observability
externalDocs:
description: Transparency read-only API (separate service spec)
url: >-
https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
/v1/agents/{agentId}/kill:
post:
tags:
- Machine Identity
summary: Emergency Kill Switch
description: |
Emergency kill switch that immediately revokes the agent, terminates all
active sessions, and optionally cascades to downstream delegated agents.
operationId: maip.agents.kill
parameters:
- name: agentId
in: path
required: true
schema:
type: string
format: uuid
description: Agent identifier
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- reason
properties:
reason:
type: string
description: Reason for emergency kill
cascade:
type: boolean
default: false
description: If true, also kill all agents this agent delegated to
responses:
'200':
description: Agent killed
content:
application/json:
schema:
type: object
properties:
agent:
$ref: '#/components/schemas/MaipAgent'
terminated_sessions:
type: integer
description: Number of sessions terminated
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- APIKey: []
components:
schemas:
MaipAgent:
type: object
properties:
id:
type: string
format: uuid
agent_type:
type: string
enum:
- orchestrator
- worker
- inference
- pipeline
- service
- bot
- llm
display_name:
type: string
maxLength: 256
description:
type: string
status:
type: string
enum:
- active
- suspended
- revoked
scopes:
type: array
items:
type: string
metadata:
type: object
additionalProperties: true
trust_score:
type: number
format: float
minimum: 0
maximum: 1
public_key:
type: string
description: Base64-encoded public key
session_count:
type: integer
keys:
type: array
items:
type: object
properties:
kid:
type: string
algorithm:
type: string
public_key:
type: string
status:
type: string
enum:
- active
- disabled
- expired
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
ErrorEnvelope:
type: object
required:
- code
- message
- http_status
properties:
code:
type: string
description: Machine-readable error code
enum:
- AUTH_REQUIRED
- AUTH_INVALID
- PERMISSION_DENIED
- TENANT_IDENTITY_UNVERIFIED
- NOT_FOUND
- VALIDATION_ERROR
- CONFLICT
- PAYLOAD_TOO_LARGE
- RATE_LIMIT_EXCEEDED
- QUOTA_EXCEEDED
- SERVICE_UNAVAILABLE
- INTERNAL_ERROR
message:
type: string
description: Human-readable error message
http_status:
type: integer
description: HTTP status code
retry_after_ms:
type: integer
description: Milliseconds to wait before retrying (for rate limits)
details:
type: object
description: Additional error context
example:
code: AUTH_REQUIRED
message: Authentication required
http_status: 401
securitySchemes:
APIKey:
type: apiKey
in: header
name: X-API-Key
description: API key for machine-to-machine authentication
````