Admin workflows

You'll: grant a tenant_admin role, audit quota usage at the partner and tenant level, and rotate a webhook signing secret. These are the operator workflows you'll do most often.

All examples use the Python SDK's admin sub-client. The same operations are available in the browser at /admin/; this tutorial covers the programmatic / scripted version.

Setup#

You need a token with admin-level scope. For the SDK that means authenticating as a user who holds at least tenant_admin (or higher) for the operations below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

import os
from scaiscribe import Client, ScaiKeyAuth

client = Client(
    "https://scaiscribe.scailabs.ai",
    auth=ScaiKeyAuth(
        client_id=os.environ["SCAIKEY_CLIENT_ID"],
        client_secret=os.environ["SCAIKEY_CLIENT_SECRET"],
    ),
    default_tenant_id=os.environ["SCAISCRIBE_TENANT_ID"],
)

admin = client.admin

Workflow 1 — Grant a role#

A new colleague joins the marketing tenant. Make them a tenant_admin:

1
2
3
4
5
6
7
8

role = admin.grant_role(
    "usr_alice_marketing",
    role="tenant_admin",
    tenant_scaikey_id="tnt_marketing",
)

print(f"Granted role_id={role.role_id} at {role.granted_at}")
print(f"By: {role.granted_by_scaikey_id}")

Confirm the grant:

1
2
3

roles = admin.list_user_roles("usr_alice_marketing")
for r in roles:
    print(f"  {r.role} on tenant={r.tenant_scaikey_id} (active: {r.revoked_at is None})")

Revoke later if needed:

1

admin.revoke_role("usr_alice_marketing", role.role_id)

Revocation stamps revoked_at on the row — it stays in the database for audit. You can still list it with include_revoked=True.

Role precedence cheat sheet#

The server enforces this — attempts to grant above your level get a 403.

Workflow 2 — Partner quota rollup#

End of month — check how much your partner's tenants used:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

rollup = admin.partner_quota_rollup(
    "prt_acme",
    axis="renders_per_day",
)

print(f"Partner: {rollup.partner_scaikey_id}")
print(f"Across {rollup.tenant_count} tenant(s)")
print(f"Total today: {rollup.total_used} / {rollup.total_limit}\n")

print("Per tenant:")
for t in sorted(rollup.per_tenant, key=lambda x: -x.used):
    pct = (t.used / t.limit * 100) if t.limit > 0 else 0
    print(f"  {t.tenant_id}: {t.used}/{t.limit} ({pct:.0f}%)")

Output:

1
2
3
4
5
6
7
8
9

Partner: prt_acme
Across 12 tenant(s)
Total today: 4823 / 12000

Per tenant:
  tnt_alpha: 1450/1000 (145%)    ← over quota; got 429s today
  tnt_beta:   850/1000 (85%)
  tnt_gamma:  742/1000 (74%)
  ...

The tnt_alpha over-quota signal is real: tenants over 100% are returning 429 to their callers. Bump their quota (code change in _DEFAULTS for now; per-tenant overrides arrive in v1.x) or have a conversation.

Other axes work the same way:

1
2
3

admin.partner_quota_rollup("prt_acme", axis="documents_count")
admin.partner_quota_rollup("prt_acme", axis="assets_bytes")
admin.partner_quota_rollup("prt_acme", axis="templates_count")

Workflow 3 — Per-user breakdown within a tenant#

Someone's tenant got a 429 yesterday. Who's responsible?

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

rollup = admin.tenant_user_quota_rollup(
    "tnt_alpha",
    axis="renders_per_day",
)

print(f"Coverage: {rollup.coverage}")
print(f"Total: {rollup.total_used}\n")

for u in sorted(rollup.per_user, key=lambda x: -x.used):
    print(f"  {u.user_scaikey_id}: {u.used}")

Output:

1
2
3
4
5
6

Coverage: full
Total: 1450

  usr_batch_runner: 1240   ← the culprit
  usr_alice:         140
  usr_bob:            70

A batch job ran the tenant into the ceiling. Decide: rate-limit the batch, raise the tenant's quota, or move the batch to its own tenant.

Coverage matrix reminder#

The coverage field reports whether per-user attribution is available for the axis:

When coverage is none, per_user is empty and note explains. v1.x will close those gaps.

Workflow 4 — Rotate a webhook signing secret#

ScaiKey webhook calls into /v1/internal/scaikey/webhook carry an HMAC signature computed with a shared secret. Rotate when you suspect compromise or as part of a routine quarterly drill:

1
2
3
4
5
6

# Superadmin-only
rotation = admin.rotate_webhook_secret()

print(f"New secret: {rotation.new_secret}")
print(f"Rotated at: {rotation.rotated_at}")
print(rotation.note)

Sample output:

1
2
3
4
5
6

New secret: aBc123_XyZ-456...64-char-url-safe-base64...
Rotated at: 2026-06-14T08:42:17+00:00
Note: Install this value on the ScaiKey application's webhook
      configuration, then set SCAISCRIBE_SCAIKEY_WEBHOOK_SECRET to
      the same value and restart scaiscribe-api. Until both sides
      match, webhook events will return 401 signature mismatch.

The new secret is shown once. Do this immediately:

1. Open the ScaiKey admin panel; navigate to the ScaiScribe application's webhook settings.
2. Paste the new secret in the secret field. Save.
3. SSH to the ScaiScribe backend host. Edit .env:
   bashCopy

   1	SCAISCRIBE_SCAIKEY_WEBHOOK_SECRET=<the-new-secret>

4. Restart the API process: systemctl restart scaiscribe-api (or equivalent).
5. Confirm: trigger a webhook (e.g. a ScaiKey user update) and check the access log for 200.

Between step 1 and step 4, webhook events return 401 (signature mismatch). Plan the rotation for a maintenance window or accept a brief gap in user-sync events — the daily reconciliation at 03:00 UTC catches anything missed.

Workflow 5 — Inspect a failed job#

A render came back 500. What happened?

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# Get the job
job = admin.get_job("job_01HXYZ...")

print(f"Status: {job.status}")
print(f"Operation: {job.operation}")
print(f"Submitted: {job.submitted_at}")
print(f"Completed: {job.completed_at}")
print(f"\nError: {job.error}\n")

if job.result_json:
    print("Result payload:")
    import json
    print(json.dumps(job.result_json, indent=2))

Sample output for a failed PDF render:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

Status: failed
Operation: render_pdf
Submitted: 2026-06-14T08:30:15+00:00
Completed: 2026-06-14T08:30:48+00:00

Error: gotenberg returned 502: upstream timed out

Result payload:
{
  "code": "RENDER_FAILED",
  "message": "gotenberg returned 502: upstream timed out",
  "job_id": "job_01HXYZ...",
  "doc_id": "doc_01HXYZ...",
  "version": 2
}

The error envelope mirrors what the caller saw. Combined with the operation and document/version refs, you can reproduce the failure locally.

Going further#

• The admin SPA at /admin/ exposes all of these workflows in a browser UI. Use it for ad-hoc exploration.
• The runbook at docs/manual/operations/runbook.md (operator manual) lists health-check endpoints, common-task recipes, troubleshooting, and capacity signals.
• For batch operations (e.g. grant the same role to 50 users), script with the SDK — the admin sub-client is idempotent where it can be and surfaces structured errors where it can't.

Where to next#

• Concepts → Auth + quotas — the model behind the rollup endpoints.
• Reference → SDKs — admin sub-client method-by-method coverage matrix.
• Reference → API — /v1/admin/* shapes.