> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Security API

> Kill switch, quarantine, lifecycle, ownership, relationships, and security posture

All endpoints on this page except the read-only ownership and relationship lookups require the `admin` scope.

## Kill Switch

### Block an Agent

```
POST /agents/{agent_id}/block
```

Immediately blocks the agent from making requests through the proxy.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/block \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Suspected credential leak" }'
```

### Unblock an Agent

```
POST /agents/{agent_id}/unblock
```

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/unblock \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

## Quarantine

### Quarantine an Agent

```
POST /agents/{agent_id}/quarantine
```

Flags a shadow or misbehaving agent as quarantined and blocks it in the proxy layer.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/quarantine \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Unregistered agent discovered calling production models" }'
```

### Release from Quarantine

```
POST /agents/{agent_id}/release-quarantine
```

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/release-quarantine \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### List Quarantined Agents

```
GET /agents/quarantined
```

```bash theme={null}
curl https://api.meshai.dev/api/v1/agents/quarantined \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

## Lifecycle

### List Expired Agents

```
GET /agents/expired
```

Agents whose `expires_at` has passed.

```bash theme={null}
curl https://api.meshai.dev/api/v1/agents/expired \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### List Agents Due for Review

```
GET /agents/due-review
```

Agents whose `review_date` has passed.

```bash theme={null}
curl https://api.meshai.dev/api/v1/agents/due-review \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### Configure Lifecycle

```
PATCH /agents/{agent_id}/lifecycle
```

Sets an agent's expiry date, access review cadence, and/or sponsor. All fields are optional; `review_frequency` must be `weekly`, `monthly`, `quarterly`, or `annually` and drives the computed `review_date`.

```bash theme={null}
curl -X PATCH https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/lifecycle \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_at": "2026-12-31T00:00:00Z",
    "review_frequency": "quarterly",
    "sponsor_id": "hcunha"
  }'
```

## Ownership (ABAC)

### Assign an Owner

```
POST /agents/{agent_id}/owners
```

`owner_type` must be `user`, `team`, or `service_account`. `owner_id` is a caller-supplied external identifier (e.g. an SSO user ID), not a MeshAI-generated ID. `permissions` defaults to `{"can_invoke": true, "can_configure": false, "can_delete": false}` when omitted.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/owners \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "owner_type": "user",
    "owner_id": "sso-user-4821",
    "owner_name": "Jane Doe"
  }'
```

### List Agent Owners

```
GET /agents/{agent_id}/owners
```

Requires the `registry:read` scope.

```bash theme={null}
curl https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/owners \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### Remove an Owner

```
DELETE /agents/{agent_id}/owners/{owner_id}
```

`owner_id` here is the integer ID of the ownership record returned by `POST /agents/{agent_id}/owners` (not the external `owner_id` string).

```bash theme={null}
curl -X DELETE https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/owners/7 \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

Returns `204 No Content` on success.

### List Agents by Owner

```
GET /owners/{owner_id}/agents
```

Requires the `registry:read` scope. `owner_id` is the external identifier used when the owner was assigned.

```bash theme={null}
curl https://api.meshai.dev/api/v1/owners/sso-user-4821/agents \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

## Relationships

### Agent Relationships

```
GET /agents/{agent_id}/relationships
```

Requires the `registry:read` scope. Lists the models, providers, tools, and other agents this agent calls.

```bash theme={null}
curl https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/relationships \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### Relationship Graph

```
GET /relationships/graph
```

Requires the `registry:read` scope. Returns the full tenant-wide agent dependency graph as nodes and edges.

```bash theme={null}
curl https://api.meshai.dev/api/v1/relationships/graph \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "nodes": [
        { "id": "01HQZXK3VJ3XZ9K8QYNPBC7G4T", "name": "production-summarizer", "type": "agent", "status": "healthy", "blocked": false, "framework": "crewai" },
        { "id": "model:gpt-4o", "name": "gpt-4o", "type": "model" }
      ],
      "edges": [
        { "source": "01HQZXK3VJ3XZ9K8QYNPBC7G4T", "target": "model:gpt-4o", "type": "calls_model", "request_count": 1204 }
      ]
    }
  }
  ```
</ResponseExample>

## Security Posture

```
GET /security/posture
```

Composite tenant security score (0-100) across six weighted dimensions: agent ownership, agent expiry, access reviews, quarantine status, kill switch status, and risk classification coverage.

```bash theme={null}
curl https://api.meshai.dev/api/v1/security/posture \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "score": 78,
      "max_score": 100,
      "components": [
        { "name": "Agent Ownership", "max_score": 20, "score": 16, "detail": "8/10 agents have assigned owners" },
        { "name": "Agent Expiry", "max_score": 15, "score": 15, "detail": "No expired agents" },
        { "name": "Access Reviews", "max_score": 15, "score": 12, "detail": "1 overdue" },
        { "name": "Quarantine Status", "max_score": 15, "score": 15, "detail": "None quarantined" },
        { "name": "Kill Switch Status", "max_score": 15, "score": 10, "detail": "1 agents blocked" },
        { "name": "Risk Classification", "max_score": 20, "score": 10, "detail": "5/10 agents classified" }
      ],
      "assessed_at": "2026-03-17T10:30:00Z"
    }
  }
  ```
</ResponseExample>