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

provider_id · string · required

The identifier of the provider to block.

Request Body

reason · string

Optional explanation for the block, recorded in the trust record and audit log.

Example

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

provider_id · string · required

The identifier of the provider to unblock.

Example

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

agent_id · string · required

The identifier of the agent to block.

Request Body

reason · string

Optional explanation for the block, recorded in the agent trust record.

Example

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

agent_id · string · required

The identifier of the agent to unblock.

Example

curl -X POST http://your-node:8042/v1/admin/agents/stripe-agent/unblock

---

Responses

Block/Unblock provider → returns ProviderTrustRecord.

Block/Unblock agent → returns AgentTrustRecord.

provider_id / agent_id · string · required

Identifier of the affected entity.

reputation_score · number (float) · required

Current reputation score (unchanged by block/unblock).

blocked · boolean · required

true after a block action; false after an unblock action.

block_reason · string

The reason recorded at block time. Cleared on unblock.

updated_at · string (ISO 8601) · required

UTC timestamp of this trust record update.

---

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

provider_id · string · required

The provider whose audit log you want to retrieve.

Audit response fields

items · array

Array of ProviderAuditEvent objects.

Show ProviderAuditEvent

event_id · string (UUID) · required

Unique identifier for this audit event.

provider_id · string · required

The provider this event applies to.

kind · string · required

Event type. One of registered, revoked, key_rotated, blocked, or unblocked.

reason · string

Explanation recorded at the time of the event, if provided.

created_at · string (ISO 8601) · required

UTC timestamp when this event was recorded.

Example

curl http://your-node:8042/v1/admin/providers/acme-labs/audit

Example response

{
  "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"
    }
  ]
}