mozbridge-cli 0.2.1__tar.gz → 0.4.0__tar.gz

{mozbridge_cli-0.2.1 → mozbridge_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mozbridge-cli
-Version: 0.2.1
+Version: 0.4.0
 Summary: Command-line client for the Mozbridge deployment platform: SSO login, build, publish, status, and rollback for any project hosted on Mozbridge.
 Project-URL: Homepage, https://mozbridge.com
 Project-URL: Documentation, https://github.com/jessin01/mozbridge/blob/main/cli/docs/commands.md
@@ -250,11 +250,13 @@ written, or permission-checked in this path at all. Because of that,
 means "don't attempt an interactive login") — unset it first if you actually
 want to run the device flow.
 
-**Where the token comes from**: a project-scoped Mozbridge `ServiceToken`,
-created out of band via the Mozbridge dashboard/API
-(`create_service_token`) — the CLI never creates or mints one itself. Set it
-as your CI platform's secret store, never as a `--token` flag (it would leak
-into shell history and process listings) and never committed to the repo.
+**Where the token comes from**: a project- or org-scoped Mozbridge
+`ServiceToken`. Mint one directly from this CLI — `mozbridge token create
+--scope deploy` (requires an active `mozbridge login` session; see
+`mozbridge token create --help`) — or out of band via the dashboard/API
+(`create_service_token`). Set it as your CI platform's secret store, never
+as a `--token` flag (it would leak into shell history and process
+listings) and never committed to the repo.
 
 **`MOZBRIDGE_TOKEN` vs `MOZBRIDGE_BUILD_TOKEN` — do not confuse these**:
 

{mozbridge_cli-0.2.1 → mozbridge_cli-0.4.0}/README.md

@@ -222,11 +222,13 @@ written, or permission-checked in this path at all. Because of that,
 means "don't attempt an interactive login") — unset it first if you actually
 want to run the device flow.
 
-**Where the token comes from**: a project-scoped Mozbridge `ServiceToken`,
-created out of band via the Mozbridge dashboard/API
-(`create_service_token`) — the CLI never creates or mints one itself. Set it
-as your CI platform's secret store, never as a `--token` flag (it would leak
-into shell history and process listings) and never committed to the repo.
+**Where the token comes from**: a project- or org-scoped Mozbridge
+`ServiceToken`. Mint one directly from this CLI — `mozbridge token create
+--scope deploy` (requires an active `mozbridge login` session; see
+`mozbridge token create --help`) — or out of band via the dashboard/API
+(`create_service_token`). Set it as your CI platform's secret store, never
+as a `--token` flag (it would leak into shell history and process
+listings) and never committed to the repo.
 
 **`MOZBRIDGE_TOKEN` vs `MOZBRIDGE_BUILD_TOKEN` — do not confuse these**:
 

{mozbridge_cli-0.2.1 → mozbridge_cli-0.4.0}/docs/commands.md

@@ -575,12 +575,25 @@ calls `POST /api/v1/projects/{project_id}/deploy` with
 gave a tag** — not the API's own default of deploying both — so the CLI only
 ever asks the platform to deploy what you specified.
 
-The backend runs a preflight check before enqueuing the deploy. A 409
-response means it found a real, known-to-fail condition and refused —
-each blocking check is printed with its title, detail, and suggested
-action, followed by a hint to re-run with `--force` if you want to override
-it. **The CLI never retries with `--force` automatically** — that is always
-a separate, explicit re-invocation.
+Before the confirmation prompt, `deploy` also proactively calls `GET
+/projects/{id}/preflight` (the platform's own pre-deploy checks) and
+prints anything at `warn`/`fail` level — title, detail, and suggested
+action — so a likely-to-fail condition is visible before you commit, not
+just after a 409. When every check is `pass`, nothing extra is printed —
+the happy path stays exactly as quiet as before this existed. A failed
+lookup here (network error, etc.) is swallowed silently and never blocks
+`deploy` — this is informational only, matching the backend's own
+fail-open design; the real gate is still the backend's own check at
+enqueue time. These checks are platform-level (registry credentials, DNS,
+disk, Vault role, and similar) — they do **not** detect a project's own
+compose/template misconfiguration.
+
+The backend also runs its own preflight check before enqueuing the
+deploy. A 409 response means it found a real, known-to-fail condition and
+refused — each blocking check is printed with its title, detail, and
+suggested action, followed by a hint to re-run with `--force` if you want
+to override it. **The CLI never retries with `--force` automatically** —
+that is always a separate, explicit re-invocation.
 
 **Example (`--yes`, single service)**:
 ```
@@ -737,6 +750,201 @@ Removed DATABASE_URL.
 
 ---
 
+## `mozbridge registry status` / `mozbridge registry set`
+
+Manages the linked project's own container-registry credential, used by
+`publish --local` builds and by platform-side deploys when no
+platform-provisioned registry applies. GET never returns a token/secret
+value — `schemas.RegistryCredentialStatus` has no such field — so there is
+no `registry get` that prints one.
+
+### `mozbridge registry status`
+
+**What it does**: `GET /api/v1/projects/{project_id}/registry`. If the
+project has its own credential configured, prints it (`registry_url`,
+`username`, `updated_at`) and stops — a project-level credential always
+takes precedence. Only when the project has none does it also call `GET
+/api/v1/organizations/{org_id}/registry` and report the org-level default
+instead, since that's what a build/deploy will actually fall back to.
+This mirrors the real resolution order
+(`app/services/registry_credentials.resolve_registry_credential`: project
+override → org default → none) rather than only ever showing the
+project's own (possibly misleading) empty state.
+
+```
+$ mozbridge registry status
+No project-level registry credential configured.
+Builds/deploys will use the ORG-level default:
+  registry_url: ghcr.io
+  username:     acme-bot
+  updated_at:   2026-09-01T12:00:00Z
+```
+
+If neither is configured:
+
+```
+$ mozbridge registry status
+No registry credential configured at the project or org level.
+`--local` builds will fail without one — run `mozbridge registry set`.
+```
+
+### `mozbridge registry set`
+
+**Flags**: `--url` (default `ghcr.io`), `--username` (required), `--token`
+(required — the registry password/token, not a Mozbridge service token).
+
+**What it does**: `PUT /api/v1/projects/{project_id}/registry`. Always
+writes the **project-level** credential — there is no `--org` flag on this
+command, so an org-level default is configured from the dashboard
+(**Organization Settings → Container Registry**), not from here. The
+backend validates the credential against the real registry before storing
+it; a bad credential is rejected with the registry's own error, not
+silently saved.
+
+```
+$ mozbridge registry set --url ghcr.io --username acme-bot --token ghp_xxx
+Registry credential set (ghcr.io, username=acme-bot).
+```
+
+**Failure modes**: not linked / not logged in, exit 1. Registry rejects
+the credential (bad token, wrong URL): the raw validation error, exit 1.
+
+---
+
+## `mozbridge secrets list` / `mozbridge secrets set`
+
+Manages the linked project's Vault-backed, per-environment/per-component
+secrets (`backend/app/features/projects/router.py`'s
+`/environments/{env}/secrets/{component}` routes) — distinct from the
+plain env-vars `env` wraps. The underlying replace-all POST endpoint
+deletes any key not included in the request; this CLI deliberately never
+calls it — `secrets set` uses PATCH (merge one key) only, and `api.py` has
+no wrapper for the replace-all route at all, so there is nothing here
+that could call it by accident.
+
+### `mozbridge secrets list`
+
+**Flags**: `--component` (`backend` default, or `frontend`/`infra`),
+`--env` (`prod` default), `--show-values` (fetch and print actual VALUES
+instead of just key names — prompts for confirmation unless `--yes` is
+also passed).
+
+**What it does**: defaults to the keys-only endpoint — no secret value
+ever leaves the server for a plain `mozbridge secrets list`. With
+`--show-values`, confirms (real secret material is about to print to your
+terminal and end up in scrollback/history — same gating as `deploy`) then
+fetches and prints actual values.
+
+```
+$ mozbridge secrets list
+backend/prod: 2 secret(s)
+  DATABASE_URL
+  STRIPE_SECRET_KEY
+```
+
+### `mozbridge secrets set KEY VALUE`
+
+**Flags**: `--component` (`backend` default), `--env` (`prod` default).
+
+**What it does**: `PATCH .../secrets/{component}` — merges this one key
+server-side over a strict read of what's already there; never touches any
+other key. There is no `secrets rm` — the backend has no single-key
+delete endpoint, only PATCH-to-add/update or the wholesale-replace POST
+this CLI avoids on purpose. Removing a key today means the dashboard, or
+accepting the replace-all risk directly.
+
+```
+$ mozbridge secrets set STRIPE_SECRET_KEY sk_live_xxx
+Set STRIPE_SECRET_KEY (backend/prod).
+```
+
+**Failure modes (both commands)**: not linked / not logged in, exit 1.
+Any other API error: the raw `ApiError` message, exit 1.
+
+---
+
+## `mozbridge token create`
+
+Mints a new Mozbridge `ServiceToken` without leaving the CLI — wraps `POST
+/api/v1/tokens` (`token_router.create_service_token`), authenticated by
+the CLI's existing human login session. A service token cannot call this
+endpoint to mint further tokens (enforced server-side), which is exactly
+why this command requires `mozbridge login`, not `MOZBRIDGE_TOKEN`.
+
+**Flags**:
+| Flag | Meaning |
+|---|---|
+| `--scope` | Repeatable. Required at least once — no silent default. Real scopes: `read`, `write`, `deploy`, `admin`, `build`. |
+| `--name` | Token name. Defaults to a generated `mozbridge-cli-<slug>-<random>` name. |
+| `--org` | Mint an org-scoped token (bound to the linked org, no single project) instead of the default project-scoped one. |
+| `--project` | Mint a project-scoped token — already the default; pass only for explicitness. Mutually exclusive with `--org`. |
+| `--expires` | A single duration: `45m`, `24h`, `30d`, `2w`. Omit for a token that never expires. |
+
+**What it does**: calls `create_service_token` with the given scopes,
+bound to the linked project (default) or org (`--org`). The raw token
+value is printed once, in full — the one place in this CLI where printing
+a real secret to the terminal is correct, since there is no `mozbridge
+token show` to retrieve it again.
+
+```
+$ mozbridge token create --scope build --expires 30d
+Token created: mozbridge-cli-acme-web-app-3f9a2c1e (project-scoped, scopes=build)
+  expires_at: 2026-10-14T12:00:00Z
+
+======================================================================
+SAVE THIS TOKEN NOW — it will never be shown again:
+
+    mbt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+Store it in a password manager or your CI provider's secret store
+immediately. There is no `mozbridge token show` — this is the only time
+the raw value is ever returned.
+======================================================================
+```
+
+**Failure modes**: no `--scope` given: clear error, exit 1, no API call.
+Both `--org` and `--project` given: clear error, exit 1. Invalid
+`--expires` format: clear error naming the expected shape, exit 1. Not
+linked / not logged in: identical messages to `publish` above, exit 1.
+Any other API error: the raw `ApiError` message, exit 1.
+
+---
+
+## `mozbridge doctor`
+
+A self-diagnostic checklist for this CLI's setup — same motivation as
+sibling package `cruxhive-mcp`'s own `cruxhive-doctor`: enough moving
+parts (cached session, per-repo link file, registry credential, optional
+build token, local docker daemon) that "is my setup actually working"
+deserves one command instead of five.
+
+**What it checks, in order**: logged in, linked (verified with a real
+`GET /projects/{id}` call, not just the presence of
+`.mozbridge/link.json`), project-level registry credential configured,
+the platform's own pre-deploy checks (the same `GET .../preflight` call
+`deploy` now runs proactively), whether `MOZBRIDGE_BUILD_TOKEN` is set,
+and whether Docker is available locally. Each check is independent — one
+erroring API call is reported as "could not check (error)" on its own
+line and never prevents the rest from running.
+
+```
+$ mozbridge doctor
+✓ Logged in: session valid
+✓ Linked: acme/web-app (.mozbridge/link.json present) — resolved via API
+○ Registry configured: no project-level registry credential configured (normal, not an error — ...)
+✓ Pre-deploy checks: all clear (runs the platform's own pre-deploy checks)
+○ MOZBRIDGE_BUILD_TOKEN set: not set — only required for `mozbridge publish --local`
+✓ Docker available: docker CLI + daemon reachable
+```
+
+**Exit code**: non-zero only when a MEANINGFUL gate failed — not logged
+in, or not linked. Registry, pre-deploy checks, `MOZBRIDGE_BUILD_TOKEN`,
+and Docker are informational only: none of them are required for every
+workflow this CLI supports, so a "not configured"/"not set"/"not found"
+result never fails the command.
+
+---
+
 ## A note on authorization for `publish` / `rollback`
 
 Both commands work today because a plain human Logto session token passes

{mozbridge_cli-0.2.1 → mozbridge_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mozbridge-cli"
-version = "0.2.1"
+version = "0.4.0"
 description = "Command-line client for the Mozbridge deployment platform: SSO login, build, publish, status, and rollback for any project hosted on Mozbridge."
 readme = "README.md"
 requires-python = ">=3.10"

{mozbridge_cli-0.2.1 → mozbridge_cli-0.4.0}/scripts/release.sh

@@ -10,8 +10,25 @@
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+REPO_ROOT="$(cd "$ROOT/.." && pwd)"
 PYPROJECT="$ROOT/pyproject.toml"
 
+# Hard first check: `git fetch` updates the remote-tracking ref, not the
+# working tree — only merge/rebase/pull do that. mozbridge-cli 0.2.0 was
+# published missing 3 commands because this build ran between a `git
+# fetch` and the merge that would have actually updated the checkout.
+# Refuse to build from a checkout that's behind origin/main.
+if command -v git >/dev/null 2>&1 && git -C "$REPO_ROOT" rev-parse --git-dir >/dev/null 2>&1; then
+  git -C "$REPO_ROOT" fetch origin main --quiet 2>/dev/null || true
+  BEHIND="$(git -C "$REPO_ROOT" rev-list --count HEAD..origin/main 2>/dev/null || echo 0)"
+  if [ "${BEHIND:-0}" != "0" ]; then
+    echo "✗ Local main is ${BEHIND} commit(s) behind origin/main." >&2
+    echo "  Run: git -C \"$REPO_ROOT\" merge --ff-only origin/main" >&2
+    echo "  then re-run this script. Refusing to build a stale release." >&2
+    exit 1
+  fi
+fi
+
 usage() {
   echo "Usage: $0 [--patch|--minor|--major] [--dry-run]" >&2
   echo "  Default bump: patch" >&2

{mozbridge_cli-0.2.1 → mozbridge_cli-0.4.0}/src/mozbridge_cli/api.py

@@ -308,6 +308,149 @@ def delete_project_env_var(
     return resp.json()
 
 
+def get_project_registry(client: httpx.Client, access_token: str, org_id: int, project_id: int) -> dict:
+    """GET /api/v1/projects/{project_id}/registry -> schemas.RegistryCredentialStatus.
+
+    {configured, registry_url, username, updated_at} — the token/secret value
+    is never returned by this route (router.py:2343-2352), by design, so
+    there is nothing here for a caller to accidentally print.
+    """
+    url = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/{project_id}/registry"
+    try:
+        resp = client.get(url, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "fetch the registry credential status")
+    return resp.json()
+
+
+def get_org_registry(client: httpx.Client, access_token: str, org_id: int) -> dict:
+    """GET /api/v1/organizations/{org_id}/registry -> schemas.RegistryCredentialStatus.
+
+    Same response shape as get_project_registry above — {configured,
+    registry_url, username, updated_at}, token never included
+    (backend/app/features/identity/router.py:521-537's get_org_registry
+    mirrors the project-level route's own never-return-the-token design).
+    This is the org's default registry credential, used as a fallback for
+    any project that has no project-level override — see
+    app/services/registry_credentials.resolve_registry_credential, whose
+    real resolution order is project override -> org default -> none.
+
+    No X-Organization-Id header: get_org_registry is gated by
+    ensure_permify_org_access(user, org_id, db), which takes org_id
+    straight from the path, not from that header — same as
+    list_organizations above, the only other /organizations route this
+    module calls.
+    """
+    url = f"{config.API_BASE_URL}{config.ORGANIZATIONS_PATH}/{org_id}/registry"
+    try:
+        resp = client.get(url, headers=_headers(access_token))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "fetch the org registry credential status")
+    return resp.json()
+
+
+def set_project_registry(
+    client: httpx.Client,
+    access_token: str,
+    org_id: int,
+    project_id: int,
+    registry_url: str,
+    username: str,
+    token: str,
+) -> dict:
+    """PUT /api/v1/projects/{project_id}/registry, body schemas.RegistryCredentialSet.
+
+    Admin-gated (ensure_permify_can_administer) and validated against the
+    real registry BEFORE storing (router.py:2355-2384) — a bad credential
+    comes back as a 400 with a real message ("Could not validate registry
+    credential: ..."), which `_raise_for_status` already surfaces via
+    ApiError, same as every other function in this module.
+    """
+    url = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/{project_id}/registry"
+    payload = {"registry_url": registry_url, "username": username, "token": token}
+    try:
+        resp = client.put(url, json=payload, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "set the registry credential")
+    return resp.json()
+
+
+def _secrets_url(project_id: int, env_slug: str, component: str) -> str:
+    """Shared path builder for the four secrets endpoints below — keeps the
+    env_slug/component path segments byte-for-byte identical across list
+    keys / get values / patch one key, rather than four separately-typed
+    f-strings that could drift apart.
+    """
+    base = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/{project_id}"
+    return f"{base}/environments/{env_slug}/secrets/{component}"
+
+
+def list_env_secret_keys(
+    client: httpx.Client, access_token: str, org_id: int, project_id: int, env_slug: str, component: str
+) -> dict:
+    """GET .../environments/{env_slug}/secrets/{component}/keys -> {keys, count}.
+
+    Key NAMES only — no values leave the server (router.py:3422-3434). This
+    is the default listing behavior for `mozbridge secrets list`.
+    """
+    url = f"{_secrets_url(project_id, env_slug, component)}/keys"
+    try:
+        resp = client.get(url, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "list secret keys")
+    return resp.json()
+
+
+def get_env_secrets(
+    client: httpx.Client, access_token: str, org_id: int, project_id: int, env_slug: str, component: str
+) -> dict:
+    """GET .../environments/{env_slug}/secrets/{component} -> dict[key, value].
+
+    Returns actual secret VALUES (router.py:3412-3419). Only called from
+    `mozbridge secrets list --show-values`, gated behind an interactive
+    confirmation (or --yes) before this is ever invoked.
+    """
+    url = _secrets_url(project_id, env_slug, component)
+    try:
+        resp = client.get(url, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "fetch secret values")
+    return resp.json()
+
+
+def patch_env_secret(
+    client: httpx.Client,
+    access_token: str,
+    org_id: int,
+    project_id: int,
+    env_slug: str,
+    component: str,
+    key: str,
+    value: str,
+) -> dict:
+    """PATCH .../environments/{env_slug}/secrets/{component}, body schemas.SecretPatch {key, value}.
+
+    Merges ONE key server-side over a strict read (router.py:3437-3453) —
+    the safe way to set one secret without touching the rest. `mozbridge
+    secrets set` MUST use this, never the POST replace-all endpoint below.
+
+    Returns {"status": "success", "key", "created", "total_keys"} — never
+    the merged secret values.
+    """
+    url = _secrets_url(project_id, env_slug, component)
+    try:
+        resp = client.patch(url, json={"key": key, "value": value}, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "set the secret")
+    return resp.json()
+
+
 def trigger_prebuilt_build(
     client: httpx.Client,
     access_token: str,
@@ -387,6 +530,47 @@ def deploy_project(
     return resp.json()
 
 
+def get_project_preflight(client: httpx.Client, access_token: str, org_id: int, project_id: int) -> dict:
+    """GET /api/v1/projects/{project_id}/preflight -> preflight.Preflight.as_dict().
+
+    Read-only (backend/app/features/projects/router.py:1534's
+    project_preflight docstring: "nothing here provisions, binds or
+    writes"). Returns:
+
+        {project_id, project_slug, host, can_deploy,
+         blocking: [key, ...], warnings: [key, ...],
+         checks: [{key, level, title, detail, action}, ...]}
+
+    (see backend/app/services/preflight.py's Preflight.as_dict; `level` is
+    one of "pass"/"warn"/"fail", `action` is None when there's nothing to
+    do). `can_deploy` is `not blocking` — exactly the 10 checks
+    run_preflight assembles (placement, host_ready, architecture, dns,
+    registry, disk, vault_role, site_placement, secrets, observability).
+    This is the SAME gate `deploy_project` above already hits reactively as
+    a 409 (`_assert_preflight_clear` calls this same `run_preflight`); this
+    wrapper lets a caller run it proactively, before committing to a
+    deploy, not instead of that reactive path.
+
+    Does not detect a project's compose/template mismatch or any other
+    app-specific misconfiguration — none of the 10 checks cover that class
+    of problem. Callers must not describe this as catching it.
+
+    The backend's own gate fails OPEN: if preflight itself cannot be
+    computed (vault down, host lookup error, etc.), the real deploy is not
+    blocked. This read-only endpoint has no gate to fail open around, but a
+    caller of this wrapper should apply the same philosophy on its own
+    side: treat an ApiError here as "could not check", not as a reason to
+    block anything itself.
+    """
+    url = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/{project_id}/preflight"
+    try:
+        resp = client.get(url, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "run pre-deploy checks")
+    return resp.json()
+
+
 def list_project_operations(
     client: httpx.Client, access_token: str, org_id: int, project_id: int, *, limit: int = 1
 ) -> list[dict]:
@@ -425,6 +609,54 @@ def get_operation(client: httpx.Client, access_token: str, org_id: int, task_id:
     return resp.json()
 
 
+def create_service_token(
+    client: httpx.Client,
+    access_token: str,
+    org_id: int,
+    *,
+    name: str,
+    token_type: str,
+    scopes: list[str],
+    project_id: int | None = None,
+    expires_at: str | None = None,
+) -> dict:
+    """POST /api/v1/tokens, body identity.token_router.TokenCreate.
+
+    Authenticated by the caller's regular LOGIN session access_token, never
+    a service token — create_service_token (token_router.py:146) is gated
+    by get_current_user and explicitly rejects a service-token caller (403
+    "Service tokens cannot mint new tokens"), a deliberate anti-escalation
+    design. `org_id` is sent as the X-Organization-Id header for
+    consistency with every other call in this module, though this route
+    does not itself depend on get_current_org: `org_id` in the JSON body
+    only matters for an org-scoped token (the backend 400s without it), and
+    is ignored/overwritten server-side for a project-scoped one
+    (project.organization_id wins over anything the client sends).
+
+    `project_id`/`expires_at` are omitted from the body entirely when None,
+    same "let the backend's own default apply" convention as trigger_build
+    above — expires_at omitted means the token never expires (schemas
+    default), project_id omitted means an org-scoped token.
+
+    Returns TokenCreated: the full token record plus `token`, the raw value
+    — shown exactly once here, never retrievable from the API again.
+    """
+    payload: dict = {"name": name, "type": token_type, "scopes": scopes}
+    if project_id is not None:
+        payload["project_id"] = project_id
+    if token_type == "org":
+        payload["org_id"] = org_id
+    if expires_at is not None:
+        payload["expires_at"] = expires_at
+    url = f"{config.API_BASE_URL}{config.TOKENS_PATH}"
+    try:
+        resp = client.post(url, json=payload, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "create the service token")
+    return resp.json()
+
+
 def operation_stream_url(task_id: str) -> str:
     """URL for GET /api/v1/projects/operations/{task_id}/stream (SSE).