Admin API

Driftstack's admin API is a small, opt-in surface gated behind the driftstack_internal_admin scope. It exists so the Driftstack team can look up customer orders, apply manual recoveries when an external provider misbehaves, and attach internal-only operator notes. This page documents what it can do — so a customer doing security review can verify the scope.

The scope

Every admin endpoint is preHandler-gated on driftstack_internal_admin. Customer key-management APIs cannot grant that scope. Production staff access uses a normal authenticated web session whose exact account email is present in the server's boot-time staff allowlist; the configured project-owner account is included in that authority. There is no public or self-service "promote to admin" operation. The route examples below are not an exhaustive specification — the generated OpenAPI document is the authoritative current route list.

What admin authority cannot do

Impersonate a customer or turn an admin credential into a customer-scoped API credential. Bounded admin routes can inspect cross-account session and API-key metadata, force-destroy a session, and revoke a key, but they do not reveal API-key plaintext or expose customer-scoped resources through impersonation. Desktop recordings are local files and never enter the admin API.
Issue a crypto refund. Crypto payments are non-refundable by policy; there is no admin endpoint that initiates a crypto-side reversal. See /legal/refunds for the binding rules. Stripe refund handling is unchanged and runs through the Stripe dashboard with audit-only records on our side.
Charge a customer. Stripe + NowPayments are the only money-moving paths and neither is reachable from the admin scope.

Endpoints

Crypto orders

Endpoint	Purpose
`GET /v1/admin/crypto-orders`	Cross-account list. Filters: `status`, `search`, `payment_id`, `account_id`, `created_after` / `created_before`. Cursor-paginated via `next_cursor`.
`GET /v1/admin/crypto-orders.csv`	Same filter set, CSV export (up to 1000 rows / call).
`GET /v1/admin/crypto-orders/stats`	Per-status counts, paid revenue by currency, avg time-to-paid.
`GET /v1/admin/crypto-orders/idempotency-metrics`	Counters for first-write vs replay vs body-mismatch on the customer checkout endpoint.
`GET /v1/admin/crypto-orders/pending-age`	Histogram of how long current pending orders have been pending — surfaces stuck flows.
`GET /v1/admin/crypto-orders/daily?days=N`	Per-day breakdown of (date, status, count) for charts.
`GET /v1/admin/crypto-orders/:order_id`	Single-order lookup with the full envelope (including internal note).
`GET /v1/admin/crypto-orders/:order_id/events`	Per-order event stream (state transitions + admin actions, append-only).
`POST /v1/admin/crypto-orders/:order_id/apply-ipn`	Manually replay a missed NowPayments IPN. Forward-only state machine.
`PATCH /v1/admin/crypto-orders/:order_id/internal-note`	Set / clear the admin-only internal note on an order.
`POST /v1/admin/crypto-orders/sweep-expired`	Bulk-expire pending orders older than N hours.

Status subscribers

Endpoint	Purpose
`GET /v1/admin/status-subscribers`	List subscriber rows with `limit` (1–200) and `offset` (0 or greater). The response envelope is `{ data: [...] }`; this route does not return a cursor.
`POST /v1/admin/status-subscribers/force-subscribe`	Add or restore an address only when staff has documented out-of-band consent. The write is audit-logged.
`POST /v1/admin/status-subscribers/:id/force-unsubscribe`	Mark the exact `sub_<uuid>` row unsubscribed and retain its tombstone. The write is audit-logged.

Other admin surfaces

The crypto-orders surface is documented in detail because it sees the most external interest. Representative additional routes cover:

Account lifecycle (suspend / unsuspend / restore).
Cross-account session and API-key metadata plus bounded force actions.
Webhook delivery dead-letter inspection and recovery.
Health probe + incident management for the public status page.
Cost-monitoring alert overrides.
Audit-log inspection.

Each is gated on the same scope and is audit-logged.

Audit logging

Every admin write lands in admin_audit_log with the acting admin key id, the action, the resource it touched, and a timestamp. The customer-facing audit log page documents the schema. This page does not claim an active R2 archive pipeline; retention follows the published legal and operational policy.

Staff access and revocation

Staff sign in through the same web-session flow as other users. At authentication time, the server adds driftstack_internal_admin only when the account email matches DRIFTSTACK_STAFF_EMAILS or the configured DRIFTSTACK_OWNER_EMAIL. The allowlist is loaded at boot, so a configuration change requires a controlled API restart.

Revoke the affected web session and remove the email from staff authority (or change the owner configuration) before that restart. Customer-facing key creation and rotation can never mint this staff scope. Driftstack does not publish a separate admin-key CLI.