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

# Workspace control plane tutorial

> End-to-end setup for workspace mappings, audit, credential minting, kill switch, and feedback with Python SDK.

This tutorial is for teams building secure enterprise agent operations.

## What you will build

1. Sync workspace agent identity mappings.
2. Query workspace-scoped audit data.
3. Mint short-lived credentials for follow-on operations.
4. Revoke credentials and use kill switches during incidents.
5. Submit reputation feedback signals.

## Prerequisites

* Python 3.9+
* `pip install clawb-agent-sdk`
* One workspace API key (`ck_live_...` or `ck_test_...`)
* One existing `agent_id`

## Step 1: setup client objects

<CodeGroup>
  ```bash curl theme={null}
  export CLAWB_BASE_URL="https://api.clawb.ai/api"
  export CLAWB_API_KEY="ck_test_replace_me"
  ```

  ```python Python SDK theme={null}
  from clawb_agent_sdk import ClawbClient, WorkspaceControlPlane

  BASE_URL = "https://api.clawb.ai/api"
  WORKSPACE_API_KEY = "ck_test_replace_me"

  client = ClawbClient(base_url=BASE_URL)
  control_plane = WorkspaceControlPlane(client=client, api_key=WORKSPACE_API_KEY)
  ```
</CodeGroup>

## Step 2: upsert workspace mapping

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -X POST "$CLAWB_BASE_URL/v1/workspace/agents/upsert" \
    -H "Content-Type: application/json" \
    -H "X-Clawb-Api-Key: $CLAWB_API_KEY" \
    -d '{
      "external_agent_key":"internal:payments-bot",
      "agent_id":"agt_01replace",
      "display_name":"Payments automation bot",
      "labels":["prod","payments"],
      "environment":"prod",
      "source":"workspace_api",
      "status":"active"
    }'
  ```

  ```python Python SDK theme={null}
  mapping = control_plane.workspace_agents_upsert(
      external_agent_key="internal:payments-bot",
      agent_id="agt_01replace",
      display_name="Payments automation bot",
      labels=["prod", "payments"],
      environment="prod",
      source="workspace_api",
      status="active",
  )
  print(mapping)
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "item": {
      "external_agent_key": "internal:payments-bot",
      "agent_id": "agt_01replace",
      "environment": "prod",
      "status": "active"
    }
  }
  ```
</CodeGroup>

## Step 3: mint short-lived credential

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -X POST "$CLAWB_BASE_URL/v1/identity/credentials/mint" \
    -H "Content-Type: application/json" \
    -H "X-Clawb-Api-Key: $CLAWB_API_KEY" \
    -d '{
      "agent_id":"agt_01replace",
      "provider":"sendgrid",
      "audience":"clawb.provider",
      "ttl_seconds":300,
      "one_time":true,
      "scopes":["email:send"],
      "token_type":"jwt"
    }'
  ```

  ```python Python SDK theme={null}
  mint = control_plane.identity_credentials_mint(
      agent_id="agt_01replace",
      provider="sendgrid",
      audience="clawb.provider",
      ttl_seconds=300,
      one_time=True,
      scopes=["email:send"],
      token_type="jwt",
  )
  print(mint["credential"]["cred_id"])
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "credential": {
      "cred_id": "crd_01...",
      "token_type": "jwt",
      "expires_at": "2026-02-28T00:05:00Z",
      "one_time": true
    }
  }
  ```
</CodeGroup>

## Step 4: query audit events

<CodeGroup>
  ```bash curl theme={null}
  curl -sS "$CLAWB_BASE_URL/v1/workspace/audit/events?limit=20" \
    -H "X-Clawb-Api-Key: $CLAWB_API_KEY"
  ```

  ```python Python SDK theme={null}
  audit = control_plane.workspace_audit_events(limit=20)
  for event in audit.get("items", []):
      print(event["created_at"], event["event_type"], event.get("decision"))
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "items": [
      {
        "event_id": "evt_01...",
        "event_type": "policy_check",
        "decision": "deny",
        "created_at": "2026-02-28T00:00:00Z"
      }
    ],
    "next_cursor": "cur_01..."
  }
  ```
</CodeGroup>

## Step 5: incident response controls

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -X POST "$CLAWB_BASE_URL/v1/identity/kill-switch/minting" \
    -H "Content-Type: application/json" \
    -H "X-Clawb-Api-Key: $CLAWB_API_KEY" \
    -d '{"paused":true,"reason":"incident INC-42"}'

  curl -sS -X POST "$CLAWB_BASE_URL/v1/identity/kill-switch/revoke-all" \
    -H "Content-Type: application/json" \
    -H "X-Clawb-Api-Key: $CLAWB_API_KEY" \
    -d '{"reason":"incident INC-42"}'

  curl -sS "$CLAWB_BASE_URL/v1/identity/kill-switch/status" \
    -H "X-Clawb-Api-Key: $CLAWB_API_KEY"
  ```

  ```python Python SDK theme={null}
  control_plane.identity_kill_switch_minting(paused=True, reason="incident INC-42")
  control_plane.identity_kill_switch_revoke_all(reason="incident INC-42")
  print(control_plane.identity_kill_switch_status())
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
    "minting_paused": true,
    "all_credentials_revoked_at": "2026-02-28T00:00:00Z"
  }
  ```
</CodeGroup>

## Step 6: submit reputation feedback

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -X POST "$CLAWB_BASE_URL/v1/reputation/feedback" \
    -H "Content-Type: application/json" \
    -H "X-Clawb-Api-Key: $CLAWB_API_KEY" \
    -H "X-Clawb-Feedback-Timestamp: 1740137855000" \
    -H "X-Clawb-Feedback-Nonce: n_123" \
    -H "X-Clawb-Feedback-Signature: <base64-hmac>" \
    -d '{
      "agent_id":"agt_01replace",
      "verdict":"bad",
      "evidence":{"reason":"repeated invalid_signature attempts"}
    }'
  ```

  ```python Python SDK theme={null}
  feedback = control_plane.reputation_feedback(
      agent_id="agt_01replace",
      verdict="bad",
      evidence={"reason": "repeated invalid_signature attempts"},
  )
  print(feedback)
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "accepted": true,
    "received_at": "2026-02-28T00:00:00Z"
  }
  ```
</CodeGroup>

## Next steps

* [Workspace integration flow](/integration/workspace-flow)
* [Identity credential APIs](/api-reference/identity-credentials)
* [Workspace audit APIs](/api-reference/workspace-audit)