simple-module-api-tokens 0.0.37__tar.gz

simple_module_api_tokens-0.0.37/.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# UV
+uv.lock
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Database
+*.db
+*.sqlite3
+
+# Module-managed runtime state (e.g. uploaded dataset files,
+# default storage_dir for SM_DATASETS_STORAGE_DIR).
+var/
+
+# file_storage filesystem backend default root (override via SM_FILE_STORAGE_FS_ROOT_PATH).
+uploads/
+
+# Vite
+host/static/dist/
+
+# VitePress (docs)
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+
+# Auto-generated frontend module manifest (regenerated by the host at boot
+# or via `make gen-pages`).
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+host/client_app/modules.assets.json
+
+# Worktrees
+.worktrees/
+
+# Performance profiles
+.memray/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.playwright-cli/*
+.playwright-mcp/*
+host/client_app/.playwright-cli/*
+.superpowers/
+.qa/
+.verify/
+/openapi.json

simple_module_api_tokens-0.0.37/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simple_module_api_tokens-0.0.37/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: simple_module_api_tokens
+Version: 0.0.37
+Summary: Personal access tokens and service API keys for simple_module
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-keys,api-tokens,fastapi,personal-access-tokens,simple-module
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: simple-module-auth==0.0.37
+Requires-Dist: simple-module-core==0.0.37
+Requires-Dist: simple-module-db==0.0.37
+Requires-Dist: simple-module-hosting==0.0.37
+Requires-Dist: simple-module-inertia==0.0.37
+Requires-Dist: simple-module-settings==0.0.37
+Requires-Dist: simple-module-users==0.0.37
+Description-Content-Type: text/markdown
+
+# simple_module_api_tokens
+
+Personal access tokens and service API keys for
+[simple_module](https://github.com/antosubash/simple_module_python) apps.
+
+- `smpat_…` tokens act for their owner, `smsk_…` service keys act for no one,
+  with roles chosen at creation (never `admin`) and a pinned tenant.
+- Every token carries **scopes**, which cap what it can do on every request,
+  even when its owner is an admin. Demoting the owner shrinks the token at once.
+- Only `sha256(token)` is stored, and the secret is shown once. Revocation
+  applies on the next request.
+- Tokens can only be created, listed and revoked from a signed-in browser
+  session, with a CSRF token.
+
+## Install
+
+```bash
+pip install simple_module_api_tokens
+```
+
+Add `simple_module_api_tokens` to your host's dependencies and generate a
+migration. It needs the `auth`, `users` and `settings` modules.
+
+## Usage
+
+```bash
+curl -H "Authorization: Bearer smpat_…" https://app.example.com/api/feature_flags/
+```
+
+| Route | Page | Purpose |
+|---|---|---|
+| `GET /api-tokens/` | `ApiTokens/Index` | Your own tokens (`api_tokens.use`) |
+| `GET /admin/api-tokens/` | `ApiTokens/Admin` | All tokens and service keys (`api_tokens.manage`) |
+
+Settings: `max_lifetime_days` (default 365), DB-backed.
+
+See [docs/modules/api_tokens.md](https://github.com/antosubash/simple_module_python/blob/main/docs/modules/api_tokens.md)
+for the resolution order, the scope cap and the tenancy rules.

simple_module_api_tokens-0.0.37/README.md

@@ -0,0 +1,38 @@
+# simple_module_api_tokens
+
+Personal access tokens and service API keys for
+[simple_module](https://github.com/antosubash/simple_module_python) apps.
+
+- `smpat_…` tokens act for their owner, `smsk_…` service keys act for no one,
+  with roles chosen at creation (never `admin`) and a pinned tenant.
+- Every token carries **scopes**, which cap what it can do on every request,
+  even when its owner is an admin. Demoting the owner shrinks the token at once.
+- Only `sha256(token)` is stored, and the secret is shown once. Revocation
+  applies on the next request.
+- Tokens can only be created, listed and revoked from a signed-in browser
+  session, with a CSRF token.
+
+## Install
+
+```bash
+pip install simple_module_api_tokens
+```
+
+Add `simple_module_api_tokens` to your host's dependencies and generate a
+migration. It needs the `auth`, `users` and `settings` modules.
+
+## Usage
+
+```bash
+curl -H "Authorization: Bearer smpat_…" https://app.example.com/api/feature_flags/
+```
+
+| Route | Page | Purpose |
+|---|---|---|
+| `GET /api-tokens/` | `ApiTokens/Index` | Your own tokens (`api_tokens.use`) |
+| `GET /admin/api-tokens/` | `ApiTokens/Admin` | All tokens and service keys (`api_tokens.manage`) |
+
+Settings: `max_lifetime_days` (default 365), DB-backed.
+
+See [docs/modules/api_tokens.md](https://github.com/antosubash/simple_module_python/blob/main/docs/modules/api_tokens.md)
+for the resolution order, the scope cap and the tenancy rules.

simple_module_api_tokens-0.0.37/api_tokens/__init__.py

@@ -0,0 +1 @@
+"""ApiTokens module."""

simple_module_api_tokens-0.0.37/api_tokens/audit.py

@@ -0,0 +1,52 @@
+"""How an api_tokens row is named, and reached, from the audit log.
+
+Create and revoke are recorded by ``AuditMixin`` (the hash and
+``last_used_at`` are excluded on the model). A token is named by its own
+name and display prefix — never by anything secret.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from simple_module_core.audit_links import AuditLink
+from simple_module_db import ALL_TENANTS_OPTION
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api_tokens.constants import ADMIN_URL, AUDIT_LINK_LABEL, AUDIT_LINK_LABEL_KEY, QP_TOKEN
+from api_tokens.models import ApiToken
+
+
+async def resolve_token_labels(db: AsyncSession, ids: list[str]) -> dict[str, str]:
+    """Map token id -> ``name (prefix…)`` for every id that still resolves.
+
+    Read across tenants like the rest of the audit log: the audit screen is a
+    platform view, and the label carries nothing the row itself does not.
+    """
+    parsed: dict[uuid.UUID, str] = {}
+    for raw in ids:
+        try:
+            parsed[uuid.UUID(raw)] = raw
+        except (ValueError, AttributeError, TypeError):
+            continue
+    if not parsed:
+        return {}
+    stmt = (
+        select(ApiToken.id, ApiToken.name, ApiToken.prefix)
+        .where(ApiToken.id.in_(list(parsed)))
+        .execution_options(**{ALL_TENANTS_OPTION: True})
+    )
+    rows = (await db.execute(stmt)).all()
+    return {parsed.get(tid, str(tid)): f"{name} ({prefix}…)" for tid, name, prefix in rows}
+
+
+def build_token_audit_link() -> AuditLink:
+    return AuditLink(
+        entity_type=ApiToken.__name__,
+        url_template=f"{ADMIN_URL}?{QP_TOKEN}={{id}}",
+        label=AUDIT_LINK_LABEL,
+        label_key=AUDIT_LINK_LABEL_KEY,
+        table_name=ApiToken.__tablename__,
+        label_resolver=resolve_token_labels,
+    )

simple_module_api_tokens-0.0.37/api_tokens/constants.py

@@ -0,0 +1,76 @@
+"""Stable identifiers for the api_tokens module."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Final
+
+from auth.contracts.tokens import PAT_PREFIX, SERVICE_KEY_PREFIX
+
+MODULE_NAME: Final = "ApiTokens"
+MODULE_PACKAGE: Final = "api_tokens"
+LOCALE_NAMESPACE: Final = "api_tokens"
+
+# Modules this one needs registered first: Auth owns the resolver chain,
+# Users owns the accounts a personal token acts for, Settings stores
+# ``max_lifetime_days``.
+MODULE_AUTH: Final = "Auth"
+MODULE_USERS: Final = "Users"
+MODULE_SETTINGS: Final = "Settings"
+
+
+class TokenKind(StrEnum):
+    PERSONAL = "personal"
+    SERVICE = "service"
+
+
+KIND_PREFIX: Final = {TokenKind.PERSONAL: PAT_PREFIX, TokenKind.SERVICE: SERVICE_KEY_PREFIX}
+
+# Secret: 32 random bytes in base62, left-padded to a fixed width so a
+# well-formed token can be recognised without touching the database.
+SECRET_BYTES: Final = 32
+SECRET_LENGTH: Final = 43  # ceil(256 / log2(62))
+DISPLAY_PREFIX_LENGTH: Final = 8
+
+# Prefix is load-bearing on SQLite, which has no per-module schemas.
+TABLE_TOKEN: Final = "api_tokens_token"
+IX_TOKEN_HASH: Final = "ix_api_tokens_token_hash_tenant"
+NAME_MAX_LENGTH: Final = 100
+MAX_SCOPES: Final = 200
+
+# How stale ``last_used_at`` may get before a request rewrites it. Bounds
+# the write load to one conditional UPDATE per token per window.
+LAST_USED_WRITE_INTERVAL_SECONDS: Final = 300
+
+PERM_GROUP: Final = "API tokens"
+PERM_USE: Final = "api_tokens.use"
+PERM_MANAGE: Final = "api_tokens.manage"
+USER_ROLE: Final = "user"
+
+# Roles a service key may never hold: ``admin`` would be the wildcard on a
+# credential with no person behind it.
+FORBIDDEN_SERVICE_ROLES: Final = frozenset({"admin"})
+
+API_PREFIX: Final = "/api/api_tokens"
+VIEW_PREFIX: Final = "/api-tokens"
+ADMIN_VIEW_PREFIX: Final = "/admin/api-tokens"
+# Trailing slash: both index routes are registered at "/" under their prefix.
+USER_URL: Final = f"{VIEW_PREFIX}/"
+ADMIN_URL: Final = f"{ADMIN_VIEW_PREFIX}/"
+
+PAGE_INDEX: Final = "ApiTokens/Index"
+PAGE_ADMIN: Final = "ApiTokens/Admin"
+
+MENU_LABEL: Final = "API tokens"
+MENU_LABEL_KEY: Final = "api_tokens.nav.api_tokens"
+MENU_USER_ORDER: Final = 980
+MENU_ADMIN_ORDER: Final = 130
+MENU_ICON: Final = "key"
+
+AUDIT_LINK_LABEL: Final = "API token"
+AUDIT_LINK_LABEL_KEY: Final = "api_tokens.audit.token"
+QP_TOKEN: Final = "token"
+
+# Expiry presets offered by the pages, in days; the server accepts any whole
+# number of days up to ``max_lifetime_days``.
+EXPIRY_PRESETS_DAYS: Final = (7, 30, 90, 365)

simple_module_api_tokens-0.0.37/api_tokens/contracts/__init__.py

@@ -0,0 +1,11 @@
+"""api_tokens contracts — public interface for other modules."""
+
+from api_tokens.contracts.schemas import (
+    CreatedToken,
+    PersonalTokenCreate,
+    RevokedCount,
+    ServiceKeyCreate,
+    TokenView,
+)
+
+__all__ = ["CreatedToken", "PersonalTokenCreate", "RevokedCount", "ServiceKeyCreate", "TokenView"]

simple_module_api_tokens-0.0.37/api_tokens/contracts/schemas.py

@@ -0,0 +1,70 @@
+"""SQLModel DTOs for the api_tokens module — its public surface."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from pydantic import ConfigDict, field_validator
+from sqlmodel import Field, SQLModel
+
+from api_tokens.constants import MAX_SCOPES, NAME_MAX_LENGTH
+
+
+class TokenView(SQLModel):
+    """A token as lists show it. Never carries the secret or its hash."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    kind: str
+    name: str
+    prefix: str
+    scopes: list[str]
+    roles: list[str] = []
+    owner_user_id: uuid.UUID | None = None
+    owner_email: str | None = None
+    tenant_id: str | None = None
+    created_at: datetime | None = None
+    created_by: str | None = None
+    expires_at: datetime
+    last_used_at: datetime | None = None
+    revoked_at: datetime | None = None
+
+
+class CreatedToken(SQLModel):
+    """The one response that carries the plaintext token."""
+
+    token: str
+    item: TokenView
+
+
+class _CreateBase(SQLModel):
+    name: str = Field(min_length=1, max_length=NAME_MAX_LENGTH)
+    scopes: list[str] = Field(min_length=1, max_length=MAX_SCOPES)
+    # Bounded above by the ``max_lifetime_days`` setting, checked in the service.
+    expires_in_days: int = Field(ge=1)
+
+    @field_validator("name")
+    @classmethod
+    def _strip_name(cls, value: str) -> str:
+        stripped = value.strip()
+        if not stripped:
+            raise ValueError("name must not be blank")
+        return stripped
+
+
+class PersonalTokenCreate(_CreateBase):
+    """Create a personal access token for the signed-in user."""
+
+
+class ServiceKeyCreate(_CreateBase):
+    """Create a service key. ``roles`` may not include ``admin``."""
+
+    roles: list[str] = Field(default_factory=list, max_length=50)
+
+
+class RevokedCount(SQLModel):
+    """How many tokens a bulk revoke ended."""
+
+    revoked: int

simple_module_api_tokens-0.0.37/api_tokens/deps.py

@@ -0,0 +1,66 @@
+"""FastAPI dependencies for the api_tokens module."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Annotated
+
+from auth.contracts.schemas import UserContext
+from auth.contracts.tokens import AUTH_KIND_SESSION
+from fastapi import Depends, HTTPException, Request
+from simple_module_db.deps import get_db
+from simple_module_hosting.i18n_deps import TranslatorDep
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api_tokens.service import ApiTokenService, TokenError
+from api_tokens.settings import ApiTokensSettings
+
+
+async def get_api_token_service(db: AsyncSession = Depends(get_db)) -> ApiTokenService:
+    return ApiTokenService(db)
+
+
+def get_settings(request: Request) -> ApiTokensSettings:
+    return request.app.state.api_tokens.settings
+
+
+async def require_session_principal(request: Request, t: TranslatorDep) -> UserContext:
+    """The signed-in person — refusing any token-authenticated request.
+
+    Tokens may not mint, list or revoke tokens: a leaked token must not be
+    able to make itself permanent by creating a sibling, or hide by revoking
+    the one an administrator would look for. That covers a provider's own
+    bearer credential too (``auth_kind == "bearer"``): a fifteen-minute access
+    token must not become a year-long PAT. Only a cookie session qualifies, so
+    any request carrying an ``Authorization`` header is refused outright.
+    """
+    user = getattr(request.state, "user", None)
+    if user is None:
+        raise HTTPException(status_code=401, detail=t.t("auth.errors.not_authenticated"))
+    if (
+        getattr(user, "auth_kind", None) != AUTH_KIND_SESSION
+        or getattr(user, "scopes", None) is not None
+        or "authorization" in request.headers
+    ):
+        raise HTTPException(status_code=403, detail=t.t("api_tokens.errors.session_required"))
+    return user
+
+
+def user_uuid(user: UserContext, t) -> uuid.UUID:
+    """The signed-in user's id as a UUID; 403 for a principal that is not an account."""
+    try:
+        return uuid.UUID(str(user.id))
+    except (TypeError, ValueError):
+        raise HTTPException(
+            status_code=403, detail=t.t("api_tokens.errors.session_required")
+        ) from None
+
+
+def http_error(t, exc: TokenError) -> HTTPException:
+    """Translate a service refusal into a 422 the pages can show as-is."""
+    return HTTPException(status_code=422, detail=t.t(exc.key, **exc.params))
+
+
+ApiTokenServiceDep = Annotated[ApiTokenService, Depends(get_api_token_service)]
+SettingsDep = Annotated[ApiTokensSettings, Depends(get_settings)]
+SessionPrincipal = Annotated[UserContext, Depends(require_session_principal)]

simple_module_api_tokens-0.0.37/api_tokens/endpoints/admin_api.py

@@ -0,0 +1,98 @@
+"""JSON API for administrators: every token in the tenant, and service keys.
+
+Session-only and CSRF-checked like the personal API, and gated on
+``api_tokens.manage``. Reads and revokes are tenant-scoped (fail-closed): an
+administrator acts on the active tenant, never one named in the URL.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from simple_module_db import TenantIsolationError
+from simple_module_hosting.csrf import RequiresCsrf
+from simple_module_hosting.i18n_deps import TranslatorDep
+from simple_module_hosting.permissions import RequiresPermission
+
+from api_tokens.constants import FORBIDDEN_SERVICE_ROLES, PERM_MANAGE, TokenKind
+from api_tokens.contracts.schemas import CreatedToken, ServiceKeyCreate, TokenView
+from api_tokens.deps import ApiTokenServiceDep, SettingsDep, http_error, require_session_principal
+from api_tokens.scopes import assignable_roles, assignable_scopes, check_subset
+from api_tokens.service import ApiTokenService, TokenError
+
+router = APIRouter(
+    prefix="/admin",
+    dependencies=[
+        Depends(require_session_principal),
+        Depends(RequiresCsrf()),
+        Depends(RequiresPermission(PERM_MANAGE)),
+    ],
+)
+
+
+async def tenant_token_views(service: ApiTokenService) -> list[TokenView]:
+    tokens = await service.list_tenant()
+    emails = await service.owner_emails(tokens)
+    return [
+        service.to_view(t, emails.get(t.owner_user_id) if t.owner_user_id else None) for t in tokens
+    ]
+
+
+@router.get("/tokens", response_model=list[TokenView])
+async def list_all(service: ApiTokenServiceDep, t: TranslatorDep) -> list[TokenView]:
+    try:
+        return await tenant_token_views(service)
+    except TenantIsolationError:
+        raise HTTPException(
+            status_code=409, detail=t.t("api_tokens.errors.tenant_required")
+        ) from None
+
+
+@router.post("/service-keys", response_model=CreatedToken, status_code=201)
+async def create_service_key(
+    body: ServiceKeyCreate,
+    request: Request,
+    service: ApiTokenServiceDep,
+    settings: SettingsDep,
+    t: TranslatorDep,
+) -> CreatedToken:
+    try:
+        forbidden = sorted(set(body.roles) & FORBIDDEN_SERVICE_ROLES)
+        if forbidden:
+            raise TokenError("api_tokens.errors.role_forbidden", role=forbidden[0])
+        roles = check_subset(
+            body.roles, assignable_roles(request), "api_tokens.errors.role_not_assignable"
+        )
+        scopes = check_subset(
+            body.scopes, await assignable_scopes(request), "api_tokens.errors.scope_not_held"
+        )
+        token, plaintext = await service.create(
+            kind=TokenKind.SERVICE,
+            name=body.name,
+            scopes=scopes,
+            roles=roles,
+            expires_in_days=body.expires_in_days,
+            max_lifetime_days=settings.max_lifetime_days,
+        )
+    except TokenError as exc:
+        raise http_error(t, exc) from None
+    except TenantIsolationError:
+        raise HTTPException(
+            status_code=409, detail=t.t("api_tokens.errors.tenant_required")
+        ) from None
+    return CreatedToken(token=plaintext, item=service.to_view(token))
+
+
+@router.post("/tokens/{token_id}/revoke", response_model=TokenView)
+async def revoke_any(
+    token_id: uuid.UUID, service: ApiTokenServiceDep, t: TranslatorDep
+) -> TokenView:
+    try:
+        token = await service.get_in_tenant(token_id)
+    except TenantIsolationError:
+        token = None
+    if token is None:
+        raise HTTPException(status_code=404, detail=t.t("api_tokens.errors.not_found"))
+    await service.revoke(token)
+    return service.to_view(token)

simple_module_api_tokens-0.0.37/api_tokens/endpoints/api.py

@@ -0,0 +1,109 @@
+"""JSON API for a user's own personal access tokens.
+
+Session-only (``require_session_principal``) and CSRF-checked on every
+mutation: the pages call these with the session cookie, and a token may never
+manage tokens.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from simple_module_db import TenantIsolationError
+from simple_module_hosting.csrf import RequiresCsrf
+from simple_module_hosting.i18n_deps import TranslatorDep
+from simple_module_hosting.permissions import RequiresPermission
+
+from api_tokens.constants import PERM_USE, TokenKind
+from api_tokens.contracts.schemas import (
+    CreatedToken,
+    PersonalTokenCreate,
+    RevokedCount,
+    TokenView,
+)
+from api_tokens.deps import (
+    ApiTokenServiceDep,
+    SessionPrincipal,
+    SettingsDep,
+    http_error,
+    require_session_principal,
+    user_uuid,
+)
+from api_tokens.scopes import assignable_scopes, check_subset
+from api_tokens.service import TokenError
+
+router = APIRouter(
+    prefix="/tokens",
+    dependencies=[
+        Depends(require_session_principal),
+        Depends(RequiresCsrf()),
+        Depends(RequiresPermission(PERM_USE)),
+    ],
+)
+
+
+@router.get("/", response_model=list[TokenView])
+async def list_tokens(
+    user: SessionPrincipal, service: ApiTokenServiceDep, t: TranslatorDep
+) -> list[TokenView]:
+    tokens = await service.list_for_owner(user_uuid(user, t))
+    return [service.to_view(token) for token in tokens]
+
+
+@router.post("/", response_model=CreatedToken, status_code=201)
+async def create_token(
+    body: PersonalTokenCreate,
+    request: Request,
+    user: SessionPrincipal,
+    service: ApiTokenServiceDep,
+    settings: SettingsDep,
+    t: TranslatorDep,
+) -> CreatedToken:
+    owner = user_uuid(user, t)
+    if not await service.has_usable_account(owner):
+        # No local account the resolver could load (e.g. Keycloak): refuse
+        # instead of minting a token that can never authenticate.
+        raise HTTPException(status_code=400, detail=t.t("api_tokens.errors.account_required"))
+    try:
+        scopes = check_subset(
+            body.scopes, await assignable_scopes(request), "api_tokens.errors.scope_not_held"
+        )
+        token, plaintext = await service.create(
+            kind=TokenKind.PERSONAL,
+            name=body.name,
+            scopes=scopes,
+            expires_in_days=body.expires_in_days,
+            max_lifetime_days=settings.max_lifetime_days,
+            owner_user_id=owner,
+        )
+    except TokenError as exc:
+        raise http_error(t, exc) from None
+    except TenantIsolationError:
+        raise HTTPException(
+            status_code=409, detail=t.t("api_tokens.errors.tenant_required")
+        ) from None
+    return CreatedToken(token=plaintext, item=service.to_view(token))
+
+
+@router.post("/revoke-all", response_model=RevokedCount)
+async def revoke_all_tokens(
+    user: SessionPrincipal, service: ApiTokenServiceDep, t: TranslatorDep
+) -> RevokedCount:
+    """Revoke every personal token the signed-in user holds — the panic button.
+
+    Tokens deliberately survive a password change and "sign out everywhere"
+    (see docs/modules/api_tokens.md, Security model); this is how to end them.
+    """
+    return RevokedCount(revoked=await service.revoke_all_for_owner(user_uuid(user, t)))
+
+
+@router.post("/{token_id}/revoke", response_model=TokenView)
+async def revoke_token(
+    token_id: uuid.UUID, user: SessionPrincipal, service: ApiTokenServiceDep, t: TranslatorDep
+) -> TokenView:
+    token = await service.get_owned(token_id, user_uuid(user, t))
+    if token is None:
+        raise HTTPException(status_code=404, detail=t.t("api_tokens.errors.not_found"))
+    await service.revoke(token, cross_tenant=True)
+    return service.to_view(token)