API reference

The Driftstack HTTP API surface lives at https://api.driftstack.dev. Every endpoint is versioned under /v1/*; new majors land with explicit deprecation cycles per the policy below.

What's here

• Authentication flows — sign up, log in, verify email, MFA challenge + step-up, magic link, password reset, refresh, logout. The customer-dashboard surface; distinct from API-key bearer auth.
• Account — /v1/account/me read + edit (name, timezone, slug, region, avatar). Team-RBAC interaction notes.
• API keys — create, list, rotate (V-296 24-hour grace), revoke. Scopes table.
• Sessions — create, navigate, interact, capture, wait, destroy. Session lifecycle + concurrency caps.
• Profiles — persistent identity slots; create, list, get, patch, clone (V-313), delete. Snapshots (V-312) — capture / list / restore / delete.
• Usage — current-period meter for sessions / api-calls / data transfer with tier caps surfaced.
• Audit log — every account-level action with payload + filters + paginated read.
• Two-factor authentication — TOTP enrol / verify / disable + recovery codes; step-up gate semantics.
• Billing — subscriptions, $2.99 trial pack, Stripe Customer Portal redirect, billing-state read.
• Team RBAC — invite + accept + list + remove for multi-user teams (V-298c shipped; auth path integration is V-298d).
• Versioning policy — additive vs breaking changes, deprecation cycle, when /v2/* is justified.
• Webhook events catalog — every event type Driftstack emits, payload shape, signature verification, retry policy.
• Replaying deliveries — V-307 customer self-service replay for failed and DLQ webhook deliveries.

Practical use

• Quickstart — first session in five minutes, working samples.
• Session lifecycle — full state diagram, concurrency caps, error shapes.
• Profile management — persistent identities across sessions.

Other reference surfaces

• OpenAPI spec. Live at https://api.driftstack.dev/openapi.json; rendered via Scalar UI on the API host at /docs/. The spec is the contract for SDK consumers; a deliberately committed copy lives in the repository for SDK regeneration.
• Authentication. Bearer API keys (ds_live_… for production, ds_test_… for trial-pack tier). Web sessions on the customer dashboard use opaque sha256-hashed tokens; Bearer header in both cases.
• Rate limits. Per-tier token-bucket policy. Response headers include x-ratelimit-remaining; 429 responses include retry-after. IP-based gates also apply on unauthenticated auth endpoints (signup / login / verify-email / password-reset).