Token Management

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

Takumi Guard offers two types of tokens. Both work across all npm and PyPI package managers and are configured the same way. See the quickstart for setup commands.

Token	Prefix	How to Get	Use Case
Email-Verified Token	tg_anon_	Email registration	Personal development (no Shisho Cloud account needed)
Org User Token	tg_org_	Console or Guard API	Organization-wide installation tracking

---

Email-Verified Tokens

These endpoints apply to email-verified tokens. All requests that require authentication use Authorization: Bearer <your-api-key>.

Registration

Register your email to receive an email-verified token:

curl -X POST https://npm.flatt.tech/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "language": "en"}'

The language field is optional and defaults to "en". Set it to "ja" to receive all emails in Japanese.

Your API key is included directly in the welcome email — no link to click.

Check Token Status

curl -H "Authorization: Bearer tg_anon_xxxxxx" \
  https://npm.flatt.tech/api/v1/tokens/status

Returns usage statistics including when the token was last used.

Finding Your Token

Your API key is delivered in the welcome email you receive when you register. Since package managers store credentials in plain-text configuration files, you can also recover your token from where it was saved during setup.

note

Package managers only support plain-text credentials. This is a limitation of their authentication protocols, not a Takumi Guard design choice.

npm

Your token is stored in .npmrc (project-level or user-level ~/.npmrc):

cat ~/.npmrc | grep flatt.tech
# Output: //npm.flatt.tech/:_authToken=tg_anon_xxxxxx

For yarn berry (v2+), check .yarnrc.yml:

grep npmAuthToken .yarnrc.yml

For bun, check bunfig.toml:

grep token bunfig.toml

pip / uv

If you configured pip via pip config set (the recommended method), retrieve the saved value:

pip config get global.index-url
# Output: https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

For uv, check the environment variable:

echo $UV_INDEX_URL
# Output: https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

If you set the token via environment variables instead, check your shell profile (.bashrc, .zshrc, etc.):

echo $PIP_INDEX_URL
# Output: https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

If you configured uv via uv.toml (~/.config/uv/uv.toml for user-level, or uv.toml / pyproject.toml in your project):

grep -r flatt.tech ~/.config/uv/uv.toml uv.toml pyproject.toml 2>/dev/null

Poetry

poetry config http-basic.takumi-guard
# Output: Username: token, Password: tg_anon_xxxxxx

Rotate Your Token

If you have your current key — use the regenerate endpoint for an immediate rotation:

curl -X POST \
  -H "Authorization: Bearer tg_anon_xxxxxx" \
  https://npm.flatt.tech/api/v1/tokens/regenerate

The response contains your new key. The old key is invalidated immediately. Update all package manager configurations that use the old key:

• npm: Update .npmrc (//npm.flatt.tech/:_authToken=<new-key>)
• pip: Re-run pip config set global.index-url https://token:<new-key>@pypi.flatt.tech/simple/ (or update PIP_INDEX_URL if you used env vars)
• uv: Update UV_INDEX_URL in your shell profile
• poetry: Run poetry config http-basic.takumi-guard token <new-key>

If you lost your key — first try recovering it from your package manager configuration. If you cannot find it anywhere, re-register with the same email address:

curl -X POST https://npm.flatt.tech/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "language": "en"}'

Because your email is already verified, Takumi Guard sends an email with instructions for finding your existing token, setup commands for additional ecosystems, and a one-time reset code. The email includes a ready-to-copy command with your email and reset code pre-filled:

curl --json '{"email": "you@example.com", "code": "XXXX"}' \
  https://npm.flatt.tech/api/v1/tokens/reset

The reset code expires in 1 hour. The response contains your new key, and the old key is invalidated immediately. If the code expires, simply re-register again to receive a new one — you can repeat this process anytime.

info

You can submit your email to either npm.flatt.tech or pypi.flatt.tech — both share the same token database. The resulting token works for all ecosystems regardless of which endpoint you used.

Revoke Your Token

curl -X DELETE \
  -H "Authorization: Bearer tg_anon_xxxxxx" \
  https://npm.flatt.tech/api/v1/tokens

The token is deactivated immediately.

warning

After revocation, commands using the revoked token will fail with a 401 error across all ecosystems. Update your .npmrc, environment variables, and poetry configuration before revoking if you need to switch to a new token.

---

Organization User Tokens

Paid Feature

This feature requires an active Takumi subscription with Guard enabled. See Pricing & Billing for details.

With org user tokens, you can track and search package installations across your organization members.

When to Use Tokens

Org user tokens are useful in the following scenarios:

• Your team wants centralized visibility into which packages are being installed across all members
• You need to track installations per developer (via the user identifier)

Issuing a Token

Org user tokens can be created from the "Issue Token" button in the console, or issued by a bot via the Guard API. For an example of issuing tokens via the Guard API, see Admin Deployment.

The following steps describe how to issue a token from Shisho Cloud console.

1. Navigate to Guard > Tokens in Shisho Cloud console.
2. Click Issue Token to open the token issuance form.
3. Enter a User Identifier — a label to identify who the token is for. The identifier must be 4–255 characters and may contain letters, numbers, ., _, @, +, and -.
4. Click Issue to generate the token.

The user identifier is a label attached to the token that appears in installation logs alongside each download. It helps your team see which developer installed which package. Choose a consistent naming convention for your organization.

Example	Value	Description
Email address	alice@example.com	Easy to identify the individual
Company username	alice	Matches internal directory
Device serial + OS username	C02X1234_jdoe	Uniquely identifies device + user
Asset ID + employee ID	ASSET0042_EMP12345	Uses organization-managed IDs

warning

The token is shown only once after issuance. Copy it immediately and store it in a secure location. After you close the dialog, the token secret cannot be retrieved again — only a masked prefix is visible in the token list.

Revoking an Org User Token

To revoke an org user token, navigate to Guard > Tokens in Shisho Cloud console and click the Revoke button for the token. The token is invalidated immediately.

After revocation, update any package manager configurations that use the revoked token:

• npm: Remove or replace //npm.flatt.tech/:_authToken in .npmrc
• pip: Re-run pip config set global.index-url with a new token or revert to the public index
• uv: Update UV_INDEX_URL in your shell profile
• poetry: Run poetry config http-basic.takumi-guard token <new-token> or remove the source

Commands using the revoked token will fail with a 401 error across all ecosystems.