Rules For AI Agents

These rules apply to AI-generated Authbound integrations and human-written code.

​

Package selection

• Use @authbound/nextjs for Next.js App Router integrations.
• Use @authbound/server for server-side API calls, webhooks, Express, Hono, and issuance.
• Use @authbound/react and @authbound/vue for browser UI flows.
• Use @authbound/nuxt for Nuxt module setup, server routes, route middleware, and Vue UI flows.
• Use @authbound/core only when the higher-level framework package does not fit.

​

Key handling

• Keep AUTHBOUND_SECRET_KEY and all sk_* keys server-only.
• Use NEXT_PUBLIC_AUTHBOUND_PK or another publishable key as a browser-safe project identifier for SDK status and SSE flows; it must not authorize privileged API calls.
• Do not pass secret keys through props, JSON responses, client bundles, logs, analytics, or error messages.
• Store webhook secrets separately from API keys.

​

Verification trust model

• Browser status is for user experience.
• Webhooks and signed results are for backend state changes.
• SDK-managed session routes must validate the pending same-origin browser binding and fetch the signed result with the server secret key before setting a session cookie.
• SDK-managed browser sessions require the Web Locks API. Same-origin tabs serialize create and finalize mutations under a lock keyed by the resolved endpoint origin. Use manual session mode and server-side coordination when Web Locks are unavailable or several origins share a parent-domain cookie.
• Store final verified state in your own user, session, or workflow model when the app needs route protection.
• For high-trust operations, verify backend state before performing the operation.
• Handle UI timeout the same as expired: start a new verification and wait for webhook or signed result before granting access.
• Status subscriptions use SSE first and poll /v1/verifications/{id}/status on failure. Pass create expiresAt into subscribeToStatus when building custom UI.

​

Mutations and retries

• Use idempotency keys for verification creation and issuance offer creation.
• Make webhook handlers safe for duplicate delivery.
• Use stable business identifiers in idempotency keys, such as verify:user_123 or employee-badge:employee_123.
• Reuse the same start options while a browser verification start is pending. Concurrent starts with different options fail with verification_invalid_state.

​

PII and logging

• Do not log credentials, wallet responses, tokens, signatures, secret keys, or unnecessary personal data.
• Keep wallet-visible definition fields and authenticated management metadata free of secrets and unnecessary PII. Management metadata is not exposed to wallets.
• Put user-specific issuance data in claims, not in definition titles, aliases, labels, rendering, or metadata.

​

Testing expectations

• Test route handlers that create verifications.
• Test webhook signature success and failure.
• Test duplicate webhook delivery.
• Test UI states for pending, processing, verified, failed, canceled, expired, timeout, and error verifications.
• Test route protection for verified and unverified users.