> ## Documentation Index
> Fetch the complete documentation index at: https://hs-df36fa00.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Block or Unblock Providers and Agents — Admin Actions

> Block or unblock providers and agents. Blocked entities are rejected at invocation time with HTTP 403. Includes provider audit log access.

These endpoints let administrators place or lift blocklist restrictions on providers and agents. Invocations against a blocked entity return HTTP 403 immediately, regardless of other trust scores. Every block and unblock action is written to the provider audit log.

***

## Block a provider

```
POST /v1/admin/providers/:provider_id/block
```

Blocks a provider. All invocations against any agent belonging to this provider will be rejected until the provider is unblocked.

### Path Parameters

<ParamField path="provider_id" type="string" required>
  The identifier of the provider to block.
</ParamField>

### Request Body

<ParamField body="reason" type="string">
  Optional explanation for the block, recorded in the trust record and audit log.
</ParamField>

### Example

```bash theme={null}
curl -X POST http://your-node:8042/v1/admin/providers/acme-labs/block \
  -H 'content-type: application/json' \
  -d '{ "reason": "pending compliance review" }'
```

***

## Unblock a provider

```
POST /v1/admin/providers/:provider_id/unblock
```

Lifts the block on a provider. No request body is required.

### Path Parameters

<ParamField path="provider_id" type="string" required>
  The identifier of the provider to unblock.
</ParamField>

### Example

```bash theme={null}
curl -X POST http://your-node:8042/v1/admin/providers/acme-labs/unblock
```

***

## Block an agent

```
POST /v1/admin/agents/:agent_id/block
```

Blocks a specific agent. Invocations against this agent are rejected even if its provider remains unblocked.

### Path Parameters

<ParamField path="agent_id" type="string" required>
  The identifier of the agent to block.
</ParamField>

### Request Body

<ParamField body="reason" type="string">
  Optional explanation for the block, recorded in the agent trust record.
</ParamField>

### Example

```bash theme={null}
curl -X POST http://your-node:8042/v1/admin/agents/stripe-agent/block \
  -H 'content-type: application/json' \
  -d '{ "reason": "policy violation" }'
```

***

## Unblock an agent

```
POST /v1/admin/agents/:agent_id/unblock
```

Lifts the block on a specific agent. No request body is required.

### Path Parameters

<ParamField path="agent_id" type="string" required>
  The identifier of the agent to unblock.
</ParamField>

### Example

```bash theme={null}
curl -X POST http://your-node:8042/v1/admin/agents/stripe-agent/unblock
```

***

## Responses

**Block/Unblock provider** → returns `ProviderTrustRecord`.

**Block/Unblock agent** → returns `AgentTrustRecord`.

<ResponseField name="provider_id / agent_id" type="string" required>
  Identifier of the affected entity.
</ResponseField>

<ResponseField name="reputation_score" type="number (float)" required>
  Current reputation score (unchanged by block/unblock).
</ResponseField>

<ResponseField name="blocked" type="boolean" required>
  `true` after a block action; `false` after an unblock action.
</ResponseField>

<ResponseField name="block_reason" type="string">
  The reason recorded at block time. Cleared on unblock.
</ResponseField>

<ResponseField name="updated_at" type="string (ISO 8601)" required>
  UTC timestamp of this trust record update.
</ResponseField>

***

## Provider audit log

```
GET /v1/admin/providers/:provider_id/audit
```

Returns all audit events recorded for a provider, including registrations, revocations, key rotations, and block/unblock actions.

### Path Parameters

<ParamField path="provider_id" type="string" required>
  The provider whose audit log you want to retrieve.
</ParamField>

### Audit response fields

<ResponseField name="items" type="array">
  Array of `ProviderAuditEvent` objects.

  <Expandable title="ProviderAuditEvent">
    <ResponseField name="event_id" type="string (UUID)" required>
      Unique identifier for this audit event.
    </ResponseField>

    <ResponseField name="provider_id" type="string" required>
      The provider this event applies to.
    </ResponseField>

    <ResponseField name="kind" type="string" required>
      Event type. One of `registered`, `revoked`, `key_rotated`, `blocked`, or `unblocked`.
    </ResponseField>

    <ResponseField name="reason" type="string">
      Explanation recorded at the time of the event, if provided.
    </ResponseField>

    <ResponseField name="created_at" type="string (ISO 8601)" required>
      UTC timestamp when this event was recorded.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```bash theme={null}
curl http://your-node:8042/v1/admin/providers/acme-labs/audit
```

### Example response

```json theme={null}
{
  "items": [
    {
      "event_id": "018f6c3d-0001-7000-aaaa-000000000001",
      "provider_id": "acme-labs",
      "kind": "registered",
      "created_at": "2025-01-01T08:00:00Z"
    },
    {
      "event_id": "018f6c3d-0002-7000-aaaa-000000000002",
      "provider_id": "acme-labs",
      "kind": "blocked",
      "reason": "pending compliance review",
      "created_at": "2025-01-15T09:00:00Z"
    },
    {
      "event_id": "018f6c3d-0003-7000-aaaa-000000000003",
      "provider_id": "acme-labs",
      "kind": "unblocked",
      "created_at": "2025-01-15T11:30:00Z"
    }
  ]
}
```