API Auth Integration Models

API Auth apps are the control plane for customer API keys in your product.

They are designed for use cases such as:

1. Public developer APIs where customers self-manage keys.
2. Partner or integration APIs with explicit key ownership.
3. Internal B2B automation APIs with auditable key operations.
4. Customer-facing “API keys” settings experiences.

This page gives the full end-to-end model and then helps you choose vanity vs custom UX.

What API Auth apps include

1. Key lifecycle: create, rotate, revoke.
2. Key metadata and status management.
3. Audit logs for key usage decisions.
4. Analytics and timeseries for traffic and blocked requests.
5. Ticket-based session access model for frontend management surfaces.

Two valid models

Vanity model

You expose a dedicated API Auth management surface (like your vanity-pages implementation) and hand users into it with a short-lived access ticket.

This works best when:

1. You need to ship quickly.
2. You want battle-tested key lifecycle UX first.
3. Your product team is still validating API customer behavior.

Custom model

You build key management directly into your own product flows using hooks (useApiAuthAppSession, useApiAuthKeys, audit hooks).

This works best when:

1. Key management must be embedded in existing settings pages.
2. You need complex internal policy/approval gates.
3. You have mature product requirements and stable IA.

Shared security flow (both models)

Regardless of UI model, keep this exact trust boundary:

1. User authenticates in your app.
2. Your backend authorizes that user for API key management.
3. Backend issues short-lived api_auth_access ticket.
4. Frontend exchanges ticket with /session/ticket/exchange.
5. Frontend calls /api-auth/* endpoints with that session.

Your backend remains the policy authority. The frontend handles management UX.

End-to-end implementation blueprint

1. Provision API Auth app.
2. Define RBAC policy for who can manage keys.
3. Implement ticket issuance endpoint in your backend.
4. Choose vanity embed or custom hook UX.
5. Add audit/analytics dashboards.
6. Publish customer docs for secure key handling.

Step 1: create the API Auth app

You must create the API Auth app before issuing tickets or rendering vanity/custom UI.

import { WachtClient } from "@wacht/backend";

const client = new WachtClient({
  apiKey: process.env.WACHT_BACKEND_API_KEY!,
});

await client.apiKeys.createApiAuthApp({
  app_slug: "aa_42",
  name: "Acme Public API",
  key_prefix: "acme_live",
  description: "API keys for Acme customers",
});

Use direct HTTP only in non-SDK runtimes.

Required fields:

1. app_slug
2. name
3. key_prefix

Practical convention: app_slug = aa_<deploymentId>.

Step 2: issue management tickets

Frontend management access should use short-lived tickets with ticket_type=api_auth_access.

Backend responsibilities:

1. Validate signed-in user and tenant ownership.
2. Enforce RBAC for API key management.
3. Issue short-lived ticket scoped to api_auth_app_slug.

Step 3: pick UX surface

Vanity surface

1. Fastest path to production.
2. Lower frontend maintenance.
3. Good default for early-stage teams.

Custom surface

1. Fully integrated product UX.
2. More engineering effort and testing surface.
3. Better fit when key management is a core workflow.

Decision matrix

What to lock before implementation

1. Key scope model: user, org, or workspace.
2. Expiry policy: optional vs mandatory.
3. Rotation policy: manual only vs required cadence.
4. Revocation authority: owner-only vs admin override.
5. Audit requirements: what your support/security teams must see.

Practical recommendation

For most SaaS teams:

1. Launch with vanity pages.
2. Learn customer behavior for 1-2 release cycles.
3. Move high-value flows to custom UX where needed.

That sequence reduces risk while preserving long-term flexibility.

Related docs

1. API Auth vanity implementation
2. API Auth custom hook implementation
3. React Router useApiAuthAppSession
4. React Router useApiAuthKeys
5. Node SDK API Keys API
6. API Keys Backend API Reference

Go-live checklist

1. RBAC gate for ticket issuance is enforced server-side.
2. Ticket expiry is short and validated.
3. Key create/rotate/revoke flows verified in staging.
4. Audit logs visible to support/security owners.
5. Customer-facing key handling docs are published.