# Takumi Guard: Open-Source Token Portal for Developer Self-Service

We've published [`flatt-security/takumi-guard-portal-example`](https://github.com/flatt-security/takumi-guard-portal-example), an **open-source example portal** that lets your developers self-mint Takumi Guard organization user tokens (`tg_org_`) behind your own identity provider, without ever distributing a shared bot credential to developer machines.

## Overview

The portal sits between your developers and Guard's organization user token API. A bot credential lives only on the portal; each developer signs in through your chosen identity provider, mints a `tg_org_` token scoped to their own `user_identifier`, copies the one-time plaintext, and pastes it into the tool that needs it — `.npmrc`, a CI runner secret, a build-server credential store, or similar. From that point on the tool talks to Guard directly with the org user token; it never sees, and never needs, the bot credential.

The following diagram shows the overall flow.

```mermaid
flowchart LR
    Dev([Developer Browser])

    subgraph CustomerSide[Customer Side]
        Portal["guard-token-portal<br/>holds bot id and API key<br/>auth adapter: IAP, Basic, or custom"]
    end

    subgraph ShishoSide[Shisho Cloud]
        API["Takumi API<br/>/o/orgID/guard/org-user-tokens"]
    end

    Dev ==>|"① Sign in via IdP, then mint, list, or revoke own tokens"| Portal
    Portal ==>|"② Bot-authenticated call, scoped to caller's user_identifier"| API
    API -.->|"③ Minted token, list, or revoke ack"| Portal
    Portal -.->|"④ Plaintext shown once; list re-filtered exact-match"| Dev
```

This fills the gap between the [admin setup scripts](/docs/t/guard/features/admin-deployment), which fit best when MDM can push a shared bot credential to managed machines, and the [Takumi API](/docs/r/202605-takumi-api-guard-tokens), which fits best for fully automated CI/CD or leaver workflows. The portal is the right fit when developers need to provision a token themselves but pushing a shared bot credential through MDM is either undesirable or infeasible.

Capability detection runs per request. If the bot you configure holds the **`organization/takumi_guard_token_issuer`** role, the portal renders a mint-only page; if it holds the **`organization/takumi_manager`** role, each developer additionally sees a list of their own tokens with a per-row Revoke action. Switching between the two takes effect on the next page load with no portal redeploy.

![Manage view — the caller's own tokens with a per-row Revoke action](/docs/_md-assets/d1cbd7827d-tokens-list.png)

After minting, the plaintext token is shown **once**, alongside its metadata. The portal has no way to recover it after the page closes — the developer either pastes it into their tool config immediately or revokes and re-mints.

![After minting — the plaintext token shown once, plus token id, prefix, user identifier, and creation metadata](/docs/_md-assets/a0caad0618-token-minted.png)

Even when list and revoke are enabled, the portal exposes **only the caller's own tokens**. There is no admin view, even for organization owners, and the list / revoke handlers double-filter the result on the caller's `user_identifier` (server-side prefix filter on the Guard API, plus a byte-for-byte exact-match check on the portal) — so a forged `token_id` cannot reach a token the caller does not own.

## Getting Started

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

The repository ships with a worked deployment recipe for **Google Cloud Run + Identity-Aware Proxy + Secret Manager**, under [`examples/cloudrun/`](https://github.com/flatt-security/takumi-guard-portal-example/tree/main/examples/cloudrun). If that matches your target environment, you can deploy the portal in three steps:

1. In the Shisho Cloud console, create a bot and assign it either the **`organization/takumi_guard_token_issuer`** role (mint only) or the **`organization/takumi_manager`** role (mint + per-user list + per-user revoke). Note the bot ID (`BT01…`) and API key.
2. Clone the repository and follow the `examples/cloudrun/` README to deploy.
3. Share the portal URL with your developers. Each signed-in developer mints their own token in a couple of clicks, copies the plaintext (shown once), and pastes it into the tool that needs it.

:::warning
The shipped `basic` auth mode is intended only for local development and smoke-testing — never deploy it to production. Use the `iap` mode (Google Cloud Identity-Aware Proxy) or your own authenticator adapter when running the portal anywhere developers will actually use it.
:::

For any other identity provider, or for hosting targets other than Cloud Run, add an authenticator adapter under `internal/auth/` that implements the four-method `Authenticator` interface, and deploy the binary to your environment of choice. The shipped IAP and Basic adapters serve as worked examples.

## Note: scope

The repository is shipped as an **example implementation**, not a managed product, and has only been subjected to a baseline level of review. Verify it against your organization's security standards before running it in production, and modify it where it does not fit. Source is MIT-licensed at [github.com/flatt-security/takumi-guard-portal-example](https://github.com/flatt-security/takumi-guard-portal-example).