Skip to main content

Takumi API: Manage Guard Org User Tokens from Your Automation

· 3 min read
Takashi Yoneuchi
Takashi Yoneuchi
CTO @ GMO Flatt Security Inc.

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). 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​

Paid Feature

Organization user tokens require an active Takumi subscription with Guard enabled. See Pricing & 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:

    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. For user identifier conventions, revocation semantics, and other operational details, see Token Management.