pushmetrics-cli 0.1.0__py3-none-any.whl

pm/auth/token.py

@@ -0,0 +1,289 @@
+"""Bearer Personal Access Token (PAT) auth for the pm CLI.
+
+A PAT (``pmpat_...``) is exchanged at ``POST /api/v1/security/exchange`` for a
+short-lived, workspace-scoped FAB JWT. The JWT is then sent as
+``Authorization: Bearer <jwt>`` on subsequent requests; the backend's
+``load_user_jwt`` reads the token's ``workspace_id`` claim and installs it as the
+request's effective workspace (roles + RLS), so the token is workspace-bound end
+to end.
+
+The raw PAT is resolved from (in priority order):
+
+1. the ``PM_API_TOKEN`` environment variable (agent / CI / one-off use), or
+2. a per-profile token stored via ``pm login --token`` (keyring, or a
+   ``~/.pm/tokens.json`` fallback file chmod 0600).
+
+This path carries no cookie jar and does not touch the Auth0 device flow. It is
+deliberately kept distinct from ``StoredCredentials.pm_access_token`` (the FAB
+JWT minted by the Auth0 login path) so the two auth modes never collide.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+from dataclasses import dataclass
+
+import click
+import requests
+
+from pm.auth import jwt_cache
+from pm.auth.secret_files import read_private_json, write_private_json
+from pm.config import CONFIG_DIR, keyring_account
+from pm.log import log_request, log_response, redact_secrets, timed
+
+try:
+    import keyring
+    _KEYRING_AVAILABLE = True
+except Exception:
+    _KEYRING_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+TOKEN_ENV_VAR = "PM_API_TOKEN"
+# Distinct from store.KEYRING_SERVICE ("pushmetrics-cli") so a stored PAT never
+# overwrites or shadows the Auth0 cookie/JWT credentials for the same profile.
+KEYRING_SERVICE = "pushmetrics-cli-pat"
+FALLBACK_FILE = CONFIG_DIR / "tokens.json"
+
+
+class TokenExchangeError(click.ClickException):
+    """A PAT could not be exchanged for a JWT (disabled, invalid, or revoked).
+
+    A ``ClickException`` so it renders as a clean one-line error rather than a
+    traceback when it bubbles out of a command. ``status`` carries the HTTP
+    status the exchange endpoint answered with, so callers can word a 429
+    (rate limited) differently from a 401 without parsing the message; it is
+    ``None`` when the failure was not an HTTP status (malformed 200 body).
+    """
+
+    def __init__(self, message: str, status: "int | None" = None):
+        super().__init__(message)
+        self.status = status
+
+
+@dataclass
+class ExchangeResult:
+    access_token: str
+    expires_in: int
+
+
+# The backend's own token shape (superset/pushmetrics/security/access_token.py
+# _TOKEN_RE), copied because the CLI must not import the backend (G3). A
+# token with whitespace or control characters must be refused BEFORE it
+# reaches requests: an inner newline in a header value raises InvalidHeader,
+# whose message (and the traceback click prints for it) carries the full
+# secret (security report S1).
+_PAT_SHAPE_RE = re.compile(r"^pmpat_[A-Za-z0-9_\-]{40,64}$")
+
+# One raise site, one string: `pm login --token` reaches this check through
+# exchange_pat_for_jwt and carries no copy of its own. Never echoes the value.
+PAT_SHAPE_HINT = (
+    "That does not look like a personal access token (expected pmpat_ "
+    "followed by 40-64 letters, digits, - or _, on one line). Paste the "
+    "value exactly as shown when it was created."
+)
+
+
+# The server's own sentence for a valid PAT whose workspace's organization
+# has no active subscription (dev-api: CREDENTIAL_SUBSCRIPTION_REQUIRED_MESSAGE
+# in superset/pushmetrics/views/subscription/decorators.py). Used only when
+# the 402 body does not carry a usable message itself.
+SUBSCRIPTION_REQUIRED_MESSAGE = (
+    "Personal access tokens need an active PushMetrics subscription for this "
+    "workspace's organization. Start a trial or upgrade in the web app."
+)
+
+
+def _subscription_message(resp: requests.Response) -> str:
+    """The server owns the wording: its JSON `message` when present and a
+    non-empty string, else the fixed sentence. Never the raw body (a proxy
+    page or JSON blob), and always passed through redaction."""
+    try:
+        body = resp.json()
+    except ValueError:
+        return SUBSCRIPTION_REQUIRED_MESSAGE
+    message = body.get("message") if isinstance(body, dict) else None
+    if isinstance(message, str) and message.strip():
+        # Redact first, then cut: a cut inside a token leaves a fragment
+        # the redaction pattern no longer recognises.
+        return redact_secrets(message.strip())[:300]
+    return SUBSCRIPTION_REQUIRED_MESSAGE
+
+
+def unreachable_message(api_url: str, exc: BaseException) -> str:
+    """One template for every transport failure (exchange or request): what
+    failed, then the next command. No 3-digit status, so the agent harness's
+    `failed: NNN` scrape never mistakes it for an API denial."""
+    return (
+        f"Could not reach {api_url} ({type(exc).__name__}). Check your network "
+        f"and the API URL (--api-url, PM_API_URL, or `pm config list`)."
+    )
+
+
+def is_well_formed_pat(raw_token: str) -> bool:
+    # fullmatch, not match: `$` would accept a trailing newline, which is a
+    # header-breaking character like any other.
+    return bool(_PAT_SHAPE_RE.fullmatch(raw_token or ""))
+
+
+def exchange_pat_for_jwt(
+    session: requests.Session,
+    api_url: str,
+    raw_token: str,
+) -> ExchangeResult:
+    """Exchange a raw PAT for a short-lived workspace-scoped JWT.
+
+    The PAT travels in the ``Authorization`` header only (never the URL/body).
+    Raises ``TokenExchangeError`` on any non-200 or malformed response.
+    """
+    if not is_well_formed_pat(raw_token):
+        raise TokenExchangeError(PAT_SHAPE_HINT)
+    url = f"{api_url}/api/v1/security/exchange"
+    started = log_request(logger, "POST", url)
+    try:
+        resp = session.post(
+            url,
+            headers={"Authorization": f"Bearer {raw_token}"},
+            timeout=30,
+            # Never follow a redirect: ``requests`` would re-attach the
+            # Authorization header (and thus the raw PAT) on a same-host 302.
+            allow_redirects=False,
+        )
+    except requests.RequestException as exc:
+        # A transport error's text can embed the request (and its headers);
+        # never let it reach a traceback unredacted.
+        raise TokenExchangeError(unreachable_message(api_url, exc))
+    log_response(logger, resp, started)
+
+    if resp.status_code == 403:
+        raise TokenExchangeError(
+            "Personal access tokens are not enabled on this server.",
+            status=resp.status_code,
+        )
+    if resp.status_code == 401:
+        raise TokenExchangeError(
+            "Personal access token rejected (invalid, expired, or revoked).",
+            status=resp.status_code,
+        )
+    if resp.status_code == 402:
+        # A valid PAT for an organization without an active subscription.
+        # "failed: 402" stays in the line: the agent harness scrapes
+        # "failed: NNN" to classify the denial.
+        raise TokenExchangeError(
+            f"Token exchange failed: 402 {_subscription_message(resp)}",
+            status=resp.status_code,
+        )
+    if resp.status_code != 200:
+        # Redact in case the body echoes the Authorization header (some proxy
+        # / debug error pages do), so the raw PAT can't leak into logs.
+        raise TokenExchangeError(
+            f"Token exchange failed: {resp.status_code} "
+            f"{redact_secrets(resp.text)[:300]}",
+            status=resp.status_code,
+        )
+
+    try:
+        body = resp.json() if resp.content else {}
+    except ValueError:
+        raise TokenExchangeError(
+            "Token exchange returned a non-JSON response (got HTML/redirect)."
+        )
+
+    access_token = body.get("access_token")
+    if not access_token:
+        raise TokenExchangeError(
+            "Token exchange succeeded (200) but returned no access_token."
+        )
+
+    try:
+        expires_in = int(body.get("expires_in", 900))
+    except (TypeError, ValueError):
+        expires_in = 900
+
+    return ExchangeResult(access_token=access_token, expires_in=expires_in)
+
+
+# ── storage ─────────────────────────────────────────────────────────
+
+
+def _fallback_load_all() -> dict:
+    return read_private_json(FALLBACK_FILE)
+
+
+def _fallback_save_all(data: dict) -> None:
+    # 0600 from creation, atomically replaced: see pm.auth.secret_files.
+    write_private_json(FALLBACK_FILE, data)
+
+
+def _load_stored(profile: str) -> str | None:
+    if _KEYRING_AVAILABLE:
+        try:
+            with timed(logger, "keyring.load_token"):
+                raw = keyring.get_password(KEYRING_SERVICE, keyring_account(profile))
+            if raw:
+                return raw
+        except Exception as exc:
+            # Keyring backends fail in exotic ways (locked keychain, headless
+            # session, missing dbus). Fall through to the fallback file.
+            logger.debug("keyring token load failed for %s: %s", profile, exc)
+    return _fallback_load_all().get(profile)
+
+
+def load_token(profile: str) -> str | None:
+    """Resolve the raw PAT for ``profile``: env var first, then stored.
+
+    Returns ``None`` when neither is set (caller falls back to cookie auth).
+    """
+    env = os.environ.get(TOKEN_ENV_VAR)
+    if env and env.strip():
+        return env.strip()
+    return _load_stored(profile)
+
+
+def save_token(profile: str, raw_token: str) -> None:
+    """Persist a raw PAT for ``profile`` (keyring, else fallback file).
+
+    A new PAT invalidates any JWT cached from the previous one, so a
+    `pm login --token` never keeps presenting the old token's JWT.
+    """
+    jwt_cache.clear(profile)
+    if _KEYRING_AVAILABLE:
+        try:
+            with timed(logger, "keyring.save_token"):
+                keyring.set_password(KEYRING_SERVICE, keyring_account(profile), raw_token)
+            return
+        except Exception as exc:
+            # Fall through and persist to the 0600 fallback file instead.
+            logger.debug("keyring token save failed for %s: %s", profile, exc)
+    data = _fallback_load_all()
+    data[profile] = raw_token
+    _fallback_save_all(data)
+
+
+def clear_token(profile: str) -> None:
+    """Remove any stored PAT for ``profile`` and the JWT cached from it
+    (no-op if none stored)."""
+    jwt_cache.clear(profile)
+    if _KEYRING_AVAILABLE:
+        try:
+            keyring.delete_password(KEYRING_SERVICE, keyring_account(profile))
+        except Exception as exc:
+            # PasswordDeleteError when nothing is stored is the normal case
+            # (clear must stay idempotent); anything else is logged and we
+            # still clear the fallback file below.
+            logger.debug("keyring token delete for %s: %s", profile, exc)
+    data = _fallback_load_all()
+    if profile in data:
+        del data[profile]
+        _fallback_save_all(data)
+    if _load_stored(profile) is not None:
+        # A locked keychain can refuse the delete and still answer reads;
+        # `pm logout` must not say "logged out" over a token that still
+        # authenticates (security S7).
+        raise click.ClickException(
+            f"Could not remove the stored personal access token for profile "
+            f"{profile!r}: the OS keyring refused the delete. Unlock the keyring "
+            f"(service {KEYRING_SERVICE!r}) or remove the entry there, then run "
+            f"`pm logout` again."
+        )

pm/cli.py

@@ -0,0 +1,282 @@
+"""pm — PushMetrics CLI root."""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import time
+from dataclasses import replace
+
+import click
+
+from pm._alias import AliasedGroup
+from pm import __version__
+from pm.client.base import PMApiError
+from pm.commands._helpers import info, json_option
+from pm.config import (
+    DEFAULT_PROFILES,
+    PROFILE_KEYS,
+    get_profile,
+    load_all,
+    set_profile_field,
+)
+from pm.errors import describe_api_error
+from pm.output import emit
+
+_cli_logger = logging.getLogger("pm.cli")
+
+
+# Shown first in ``pm --help``, in this order: the commands a new user
+# needs before anything else works.
+_ACCOUNT_COMMANDS = ("login", "logout", "whoami", "token", "config")
+
+
+
+class RootGroup(AliasedGroup):
+    """Root group: the single place API failures become one-line errors
+    with a next-action hint, so no command needs its own ``except
+    PMApiError`` and no command can leak a traceback for them. (Transport
+    failures are already ``PMConnectionError`` from the session layer.)
+    Also renders ``--help`` with the account commands first."""
+
+    def format_commands(self, ctx: click.Context, formatter) -> None:
+        rows = []
+        for name in self.list_commands(ctx):
+            cmd = self.get_command(ctx, name)
+            if cmd is None or cmd.hidden:
+                continue
+            rows.append((name, cmd.get_short_help_str(limit=formatter.width - 20)))
+        account = [r for n in _ACCOUNT_COMMANDS for r in rows if r[0] == n]
+        rest = [r for r in rows if r[0] not in _ACCOUNT_COMMANDS]
+        with formatter.section("Account"):
+            formatter.write_dl(account)
+        with formatter.section("Commands"):
+            formatter.write_dl(rest)
+
+    def invoke(self, ctx: click.Context):
+        try:
+            return super().invoke(ctx)
+        except PMApiError as exc:
+            raise click.ClickException(
+                describe_api_error(exc, group=ctx.invoked_subcommand)
+            )
+
+
+_GETTING_STARTED = """\b
+Get started with a personal access token:
+  1. Create a token in the PushMetrics web app under Access Tokens.
+  2. pm login --token     paste the token at the prompt (stored securely)
+  3. pm whoami            then: pm report list, pm run list, pm report run <uid>
+"""
+
+
+@click.group(cls=RootGroup, epilog=_GETTING_STARTED)
+@click.version_option(__version__, prog_name="pm")
+@click.option(
+    "--profile",
+    default="default",
+    show_default=True,
+    envvar="PM_PROFILE",
+    help="Configuration profile to use.",
+)
+@click.option(
+    "--api-url",
+    default=None,
+    envvar="PM_API_URL",
+    help="Override the API URL for this invocation.",
+)
+@click.option(
+    "--json",
+    "json_output",
+    is_flag=True,
+    help="Output JSON.",
+)
+@click.option("--verbose", "-v", is_flag=True, help="Verbose logging to stderr.")
+@click.option(
+    "--quiet",
+    is_flag=True,
+    help="Suppress informational stderr messages. Errors still emit.",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    profile: str,
+    api_url: str | None,
+    json_output: bool,
+    verbose: bool,
+    quiet: bool,
+) -> None:
+    """PushMetrics CLI."""
+    if verbose:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            stream=sys.stderr,
+            format="%(levelname)s %(name)s: %(message)s",
+        )
+
+    resolved = get_profile(profile)
+    if api_url:
+        resolved = replace(resolved, api_url=api_url.rstrip("/"))
+
+    ctx.ensure_object(dict)
+    ctx.obj["profile"] = resolved
+    ctx.obj["json"] = json_output
+    ctx.obj["verbose"] = verbose
+    ctx.obj["quiet"] = quiet
+    ctx.obj["_t0"] = time.perf_counter()
+
+
+@cli.result_callback()
+@click.pass_context
+def _emit_total_time(ctx: click.Context, result, **kwargs) -> None:
+    if ctx.obj and ctx.obj.get("verbose"):
+        elapsed = (time.perf_counter() - ctx.obj["_t0"]) * 1000
+        _cli_logger.debug("[total] %.0fms", elapsed)
+
+
+@cli.group(name="config", cls=AliasedGroup, aliases={"ls": "list"})
+def config_group() -> None:
+    """Profiles: which PushMetrics server pm talks to."""
+
+
+@config_group.command(name="set")
+@click.argument("profile_name")
+@click.argument("key", type=click.Choice(sorted(PROFILE_KEYS)))
+@click.argument("value")
+@click.pass_context
+def config_set(ctx: click.Context, profile_name: str, key: str, value: str) -> None:
+    """Set one field of a profile.
+
+    \b
+    Example:
+      pm config set staging api_url https://staging.example.com
+    """
+    set_profile_field(profile_name, key, value)
+    info(ctx, f"Updated {profile_name}.{key}.")
+
+
+@config_group.command(name="list")
+@json_option
+@click.pass_context
+def config_list(ctx: click.Context) -> None:
+    """List profiles and active environment overrides."""
+    file_data = load_all()
+    current = ctx.obj["profile"].name
+    profile_names = sorted(set(DEFAULT_PROFILES) | set(file_data))
+
+    rows = []
+    for name in profile_names:
+        merged = {**DEFAULT_PROFILES.get(name, {}), **file_data.get(name, {})}
+        rows.append({
+            "active": name == current,
+            "profile": name,
+            "api_url": merged.get("api_url") or "",
+            "auth0_domain": merged.get("auth0_domain") or "",
+            "auth0_client_id": merged.get("auth0_client_id") or "(not set)",
+        })
+
+    env_overrides = {
+        var: value
+        for var, value in (
+            ("PM_PROFILE", os.environ.get("PM_PROFILE")),
+            ("PM_API_URL", os.environ.get("PM_API_URL")),
+            ("PM_AUTH0_DOMAIN", os.environ.get("PM_AUTH0_DOMAIN")),
+            ("PM_AUTH0_CLIENT_ID", os.environ.get("PM_AUTH0_CLIENT_ID")),
+        )
+        if value
+    }
+
+    if ctx.obj["json"]:
+        emit(
+            {"profiles": rows, "env_overrides": env_overrides},
+            json_output=True,
+        )
+        return
+
+    emit(
+        rows,
+        json_output=False,
+        columns=[
+            ("ACTIVE", lambda r: "*" if r["active"] else ""),
+            ("PROFILE", "profile"),
+            ("API_URL", "api_url"),
+            ("AUTH0_DOMAIN", "auth0_domain"),
+            ("AUTH0_CLIENT_ID", "auth0_client_id"),
+        ],
+    )
+
+    if env_overrides:
+        click.echo("")
+        click.echo("Active env-var overrides (apply to all profiles):")
+        for var, value in env_overrides.items():
+            click.echo(f"  {var}={value}")
+
+
+from pm.commands.auth import login, logout, whoami
+from pm.commands.block import block as block_group
+from pm.commands.chart import chart as chart_group
+from pm.commands.help import help_cmd
+from pm.commands.db import db as db_group
+from pm.commands.email import email as email_group
+from pm.commands.explore import explore as explore_group
+from pm.commands.favorites import favorites as favorites_group
+from pm.commands.folders import folders as folders_group
+from pm.commands.integrations import integrations as integrations_group
+from pm.commands.metrics_view import metrics_view as metrics_view_group
+from pm.commands.organizations import organizations as organizations_group
+from pm.commands.recipient import recipient as recipient_group
+from pm.commands.reports import reports as reports_group
+from pm.commands.roles import roles as roles_group
+from pm.commands.runs import runs as runs_group
+from pm.commands.saved_blocks import saved_blocks as saved_blocks_group
+from pm.commands.sftp import sftp as sftp_group
+from pm.commands.slack import slack as slack_group
+from pm.commands.slides import slides as slides_group
+from pm.commands.sql import sql as sql_group
+from pm.commands.tableau import tableau as tableau_group
+from pm.commands.token import token as token_group
+from pm.commands.users import users as users_group
+from pm.commands.webhooks import webhooks as webhooks_group
+from pm.commands.workspace import workspace as workspace_group
+
+cli.add_command(login)
+cli.add_command(logout)
+cli.add_command(whoami)
+cli.add_command(help_cmd)
+cli.add_command(token_group)
+cli.add_command(workspace_group)
+# pm-consolidation follow-up — every resource group registered ONLY under
+# its singular canonical name. The plural aliases (``reports``,
+# ``folders``, ``favorites``, ``runs``, ``users``, ``integrations``,
+# ``organizations``, ``roles``, ``saved-blocks``, ``webhooks``) and the
+# ``db`` shortform were dropped to keep one surface — singular matches
+# the API resource names (e.g. /api/v1/report/, /api/v1/folder/) and the
+# agent's canonical-action keys. Agent legacy tools migrated in commit
+# 0d898f2d80.
+cli.add_command(reports_group, name="report")
+cli.add_command(runs_group, name="run")
+cli.add_command(db_group, name="database")
+cli.add_command(users_group, name="user")
+cli.add_command(folders_group, name="folder")
+cli.add_command(integrations_group, name="integration")
+cli.add_command(webhooks_group, name="webhook")
+cli.add_command(favorites_group, name="favorite")
+cli.add_command(organizations_group, name="organization")
+cli.add_command(recipient_group)
+cli.add_command(roles_group, name="role")
+cli.add_command(saved_blocks_group, name="saved-block")
+
+# pm-foundation — factory-built block-typed groups. Singular by default;
+# every block-typed group exposes some subset of create / run / send and
+# delegates the HTTP work to BlocksClient. CRUD discovery across types is
+# `pm block` (plumbing).
+cli.add_command(sql_group)
+cli.add_command(email_group)
+cli.add_command(slack_group)
+cli.add_command(sftp_group)
+cli.add_command(chart_group)
+cli.add_command(explore_group)
+cli.add_command(metrics_view_group)
+cli.add_command(tableau_group)
+cli.add_command(slides_group)
+cli.add_command(block_group)

pm/client/__init__.py

@@ -0,0 +1,68 @@
+"""PMClient — facade exposing per-resource clients off a single session.
+
+Intended uses:
+- CLI commands: `client = PMClient.from_profile(profile); client.reports.list()`
+- Step-2 Claude tools: each `client.<resource>.<method>` is a callable tool
+
+The per-resource classes (`UsersClient`, `ReportsClient`, ...) remain importable
+directly for tests and for code that needs a single resource without paying for
+the rest. The facade just composes them onto one `PMSession`.
+"""
+from __future__ import annotations
+
+from pm.auth.session import PMSession
+from pm.client.access_tokens import AccessTokensClient
+from pm.client.blocks import BlocksClient
+from pm.client.databases import DatabasesClient
+from pm.client.favorites import FavoritesClient
+from pm.client.folders import FoldersClient
+from pm.client.integrations import IntegrationsClient
+from pm.client.organizations import OrganizationsClient
+from pm.client.recipients import RecipientsClient
+from pm.client.reports import ReportsClient
+from pm.client.roles import RolesClient
+from pm.client.runs import RunsClient
+from pm.client.saved_blocks import SavedBlocksClient
+from pm.client.tableau import TableauClient
+from pm.client.users import UsersClient
+from pm.client.webhooks import WebhooksClient
+from pm.client.workspaces import WorkspacesClient
+from pm.config import Profile
+
+
+class PMClient:
+    """Top-level client. Holds a single `PMSession` and per-resource clients.
+
+    Resource clients share the underlying session, so workspace context flows
+    through every call.
+    """
+
+    def __init__(self, session: PMSession):
+        self.session = session
+        self.users = UsersClient(session)
+        self.workspaces = WorkspacesClient(session)
+        self.reports = ReportsClient(session)
+        self.runs = RunsClient(session)
+        self.databases = DatabasesClient(session)
+        self.folders = FoldersClient(session)
+        self.integrations = IntegrationsClient(session)
+        self.webhooks = WebhooksClient(session)
+        self.favorites = FavoritesClient(session)
+        self.organizations = OrganizationsClient(session)
+        self.recipients = RecipientsClient(session)
+        self.roles = RolesClient(session)
+        self.saved_blocks = SavedBlocksClient(session)
+        self.blocks = BlocksClient(session)
+        self.tableau = TableauClient(session)
+        self.access_tokens = AccessTokensClient(session)
+
+    @classmethod
+    def from_profile(cls, profile: Profile) -> "PMClient":
+        return cls(PMSession.from_profile(profile))
+
+    def persist(self) -> None:
+        """Write the current cookiejar back to the credential store."""
+        self.session.persist()
+
+
+__all__ = ["PMClient"]

pm/client/access_tokens.py

@@ -0,0 +1,54 @@
+"""Personal Access Token CRUD endpoints (`/api/v1/access_token/`).
+
+Self-service management of the caller's own ``user``-kind tokens in the current
+workspace.
+
+``create`` is special-cased: the backend returns the raw token exactly once in a
+top-level ``token`` field alongside the serialized metadata in ``result``, so it
+returns a ``(raw_token, AccessToken)`` pair rather than just the model.
+"""
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+from pm.client.base import CrudClient, PMApiError, _unwrap_result, raise_for_status
+from pm.models.access_tokens import AccessToken
+
+
+class AccessTokensClient(CrudClient[AccessToken]):
+    base_path = "/api/v1/access_token"
+    model = AccessToken
+
+    def create(  # type: ignore[override]
+        self,
+        name: str,
+        *,
+        expires_on: Optional[str] = None,
+    ) -> Tuple[str, AccessToken]:
+        """Mint a token in the current workspace. Returns ``(raw_token, meta)``.
+
+        The raw token is shown only here — it cannot be retrieved later.
+        """
+        body: dict = {"name": name}
+        if expires_on:
+            body["expires_on"] = expires_on
+        resp = self.session.post(f"{self.base_path}/", json=body)
+        raise_for_status(resp)
+        data = resp.json()
+        raw_token = data.get("token") if isinstance(data, dict) else None
+        if not raw_token:
+            # The raw secret is returned exactly once, at create. If it's
+            # absent the create did not behave as expected - fail loudly
+            # rather than handing back (and printing) an empty token.
+            raise PMApiError(
+                resp.status_code,
+                "access token create response missing the one-time 'token' value",
+                method="POST",
+                path=f"{self.base_path}/",
+            )
+        token = self.model.model_validate(_unwrap_result(data))
+        return raw_token, token
+
+    def revoke(self, token_id: str) -> None:
+        """Soft-revoke one of the caller's own tokens by its hashid ``id``."""
+        self.delete(token_id)