# Takumi API: Manage Guard Org User Tokens from Your Automation

You can now issue, list, revoke, and probe Takumi Guard **organization user tokens** (`tg_org_`) through bot-authenticated endpoints on the Takumi API. CI/CD pipelines, onboarding scripts, MDM tooling, and other automation can manage Guard tokens programmatically without going through the console.

## Overview

The Shisho Cloud console already lets a team manager issue tokens one at a time for ad-hoc cases — for example, when a new teammate needs access on their first day (see the [April release](/docs/r/202604-takumi-guard-org-user-token)). Once token provisioning becomes ops-driven, you usually want it from a script instead: bringing a new contractor onto the registry on day zero, rotating a leaked credential without waiting on a human, or sweeping all tokens for a departed teammate from a leaver workflow.

Four endpoints cover the full lifecycle:

- `POST /o/{org_id}/guard/org-user-tokens` — issue a new token, scoped to a `user_identifier` of your choice
- `GET /o/{org_id}/guard/org-user-tokens` — list tokens (filterable by `user_identifier` prefix and status)
- `DELETE /o/{org_id}/guard/org-user-tokens/by-id/{token_id}` — revoke a token by its management ID
- `POST /o/{org_id}/guard/org-user-tokens/probe` — check whether a plaintext token is still active and owned by your organization

All endpoints authenticate via the standard `Authorization: Bearer` header. The credential is the colon-joined pair of the bot's **API key** and the bot's **ID** — both of which you obtain when you create the API key in step 1 of _Usage Example_ below:

```
Authorization: Bearer shisho_apikey_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:BT01XXXXXXXXXXXXXXXXXXXXXXXX
```

Required permissions match the equivalent console action — for example, the **`organization/takumi_guard_token_issuer`** role for mint, **`organization/takumi_manager`** for revoke.

## Usage Example

:::info Paid Feature
Organization user tokens require an active Takumi subscription with Guard enabled. See [Pricing & Billing](/docs/t/guard/billing) for details.
:::

1. In the Shisho Cloud console, create a bot under **Settings → Bots → Add Bot** and grant it the organization role appropriate for what it needs to do (`organization/takumi_guard_token_issuer` or `organization/takumi_manager`).
2. Generate an API key for the bot, then store **both the API key and the bot's ID** as secrets in your automation tool. The credential you pass to the API is the colon-joined pair (`shisho_apikey_…:BT01…`).
3. Mint a token:

   ```bash
   curl -sS https://api.cloud.shisho.dev/v1/o/$ORG/guard/org-user-tokens \
     -H "Authorization: Bearer $BOT_API_KEY:$BOT_ID" \
     --json '{"user_identifier": "alice-laptop"}'
   ```

## Full API Reference

The walkthrough above is just one minimal example. The four endpoints — issue, list, revoke, and probe — can be composed in whatever shape your automation needs, whether that is an onboarding script, an offboarding workflow, MDM-driven token rotation, or something more bespoke.

For the full request/response schemas, validation rules, and error envelopes of every endpoint, refer to the [OpenAPI spec](https://api.cloud.shisho.dev/v1/docs/openapi.json). For user identifier conventions, revocation semantics, and other operational details, see [Token Management](/docs/t/guard/features/token-management#user-tokens).