# Email Token Management {#token-management}

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

:::info One Token, All Ecosystems
Your API key (`tg_anon_…`) works across **all** Takumi Guard ecosystems — both npm and PyPI. You only need to register once. Use the same token to configure any supported package manager.
:::

## Check Token Status {#token-status}

```bash
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 {#finding-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 {#finding-token-npm}

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

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

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

```bash
grep npmAuthToken .yarnrc.yml
```

For **bun**, check `bunfig.toml`:

```bash
grep token bunfig.toml
```

### pip / uv {#finding-token-pip}

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

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

For **uv**, check the environment variable:

```bash
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.):

```bash
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):

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

### Poetry {#finding-token-poetry}

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

## Rotate Your Token {#rotating-token}

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

```bash
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](#finding-token). If you cannot find it anywhere, re-register with the same email address:

```bash
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:

```bash
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 {#revoking-token}

```bash
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.
:::