SEQN Auth API Contract

This contract describes the MVP endpoints consumed by @seqn/auth-js. It includes invitation email queuing when SMTP is configured. Password recovery, email verification, MFA, and passkey enrollment are Authentik-owned flows surfaced through safe handoff URLs when configured; payment collection remains outside the MVP.

Public client config

GET /v1/client/config
Authorization: none
X-SEQN-Publishable-Key: pk_live_...

Query fallback for constrained clients:

GET /v1/client/config?publishable_key=pk_live_...

Expected 200 response:

{
  "application": {
    "id": "app_123",
    "slug": "seqn-console",
    "name": "SEQN Console",
    "publishableKey": "pk_live_...",
    "status": "active"
  },
  "organization": {
    "slug": "seqn",
    "name": "SEQN"
  },
  "auth": {
    "signInUrl": "https://auth.seqn.in/sign-in",
    "signUpUrl": "https://auth.seqn.in/sign-up",
    "afterSignInUrl": "https://app.seqn.in",
    "afterSignUpUrl": "https://app.seqn.in"
  },
  "oidc": {
    "issuer": "https://accounts.seqn.in/application/o/silver-auth/",
    "clientId": "silver-auth"
  },
  "oauth": {
    "sharedDevelopment": {
      "mode": "shared_development",
      "provider": "google",
      "credentialsRequired": false
    },
    "production": {
      "mode": "customer_owned",
      "provider": "google",
      "credentialsRequired": true
    }
  }
}

Expected errors:

  • 400 invalid_publishable_key when the key is missing or malformed.
  • 404 application_not_found when the key is unknown.
  • 409 application_disabled when the application exists but is disabled.

Backend application health

GET /v1/backend/application
Authorization: Bearer sk_live_...

Expected 200 response:

{
  "ok": true,
  "application": {
    "id": "app_123",
    "slug": "seqn-console",
    "name": "SEQN Console",
    "status": "active",
    "secretKeyPrefix": "sk_live_abc12345"
  },
  "organization": {
    "slug": "seqn",
    "name": "SEQN"
  },
  "checkedAt": "2026-05-12T00:00:00.000Z"
}

Expected errors:

  • 401 invalid_secret_key when the secret key is missing, malformed, revoked, or unknown.
  • 409 application_disabled when the key belongs to a disabled application.

Compatibility notes

The legacy scaffold route GET /v1/config remains useful for service-level checks, but new SDK integrations should use GET /v1/client/config.

GET /v1/config also returns an account block when Authentik account-management URLs are configured:

{
  "account": {
    "engine": "authentik",
    "recoveryUrl": "https://accounts.seqn.in/if/flow/default-recovery-flow/",
    "recoveryConfigured": true,
    "emailVerificationUrl": null,
    "mfaSetupUrl": "https://accounts.seqn.in/if/user/#/settings;page=mfa",
    "passkeySetupUrl": "https://accounts.seqn.in/if/user/#/settings;page=webauthn"
  }
}

These are public handoff URLs only. SEQN Auth also exposes GET /auth/recovery, which sanitizes return_to, preserves project/keyless handoff params, and redirects to the configured Authentik recovery flow. SEQN Auth does not implement password reset, MFA enrollment, or passkey protocol logic itself.

AI agent / IDE setup context

GET /v1/setup/agent-context?publishable_key=pk_live_...&framework=nextjs
Authorization: none

Expected 200 response includes:

  • safe service/project/org metadata.
  • framework-specific install command and env variable names. Supported framework names include nextjs, react, express, fastapi, django, flask, laravel, rails, and rest.
  • redirect URLs and JavaScript origins to configure.
  • shared-development Google OAuth mode, with no customer Google credentials required for development.
  • production note that customer-owned Google OAuth credentials should be used before public launch.
  • an aiAgentPrompt string that can be pasted into an IDE/agent.

The response never includes secret keys, OAuth client secrets, identity-engine tokens, or payment-provider secrets.

Public signup workspace behavior

Hosted /sign-up and /sign-in both use the SEQN Auth identity flow. The hosted Google button starts at the configured SEQN/Auth Google source-stage flow, while the email/password option sends only an email hint into the configured Authentik password-capable OIDC flow; SEQN Auth never receives or stores the password. Both methods resume SEQN Auth's OIDC callback for session creation. A user in the configured platform admin group (SEQN-A) opens the SEQN platform workspace. Any other successful OIDC user gets a tenant workspace created automatically, is assigned org admin inside that workspace, and can open /auth/console for their own projects. Platform-only engine resource proxy routes still require the SEQN-A platform admin identity.

Admin control-plane APIs

All routes below require the hosted SEQN Auth session cookie. Mutation routes require an org admin role.

GET /v1/users?organization_slug=seqn
POST /v1/users
PATCH /v1/users/:id
GET /v1/sessions?organization_slug=seqn
POST /v1/sessions/:id/revoke?organization_slug=seqn
GET /v1/roles?organization_slug=seqn
POST /v1/roles
PATCH /v1/roles/:id
GET /v1/invitations?organization_slug=seqn
POST /v1/invitations
POST /v1/invitations/:id/revoke?organization_slug=seqn
POST /v1/invitations/accept
GET /v1/email-deliveries?organization_slug=seqn
POST /v1/email-deliveries/process

Invitation create returns invitationToken and inviteLink once. When EMAIL_ENABLED=true and EMAIL_PROVIDER=croox, SEQN Auth queues the invitation email in a durable outbox and attempts delivery through hosted Croox without exposing the raw email body or ck_... API key in the API response. Without an email provider, admins can still copy the one-time invite link manually.

When EMAIL_DELIVERY_WORKER_ENABLED=true, the API server processes due invitation email deliveries in the background using the configured interval and batch size. GET /v1/email-deliveries returns sanitized delivery metadata for org admins: recipient, subject, status, attempt count, timestamps, and public metadata. It does not return raw body text, provider messages, private metadata, unsafe metadata, or provider error text. POST /v1/email-deliveries/process lets org admins process due or selected deliveries when email delivery is enabled.

Identity OS control-plane APIs

These routes build the SaaS control plane around Authentik. Hosted session cookies are required for tenant management. POST /v1/usage/events also accepts Authorization: Bearer sk_live_... for backend usage ingestion.

GET /v1/tenants
POST /v1/tenants
GET /v1/tenants/:id
PATCH /v1/tenants/:id
DELETE /v1/tenants/:id
GET /v1/tenants/:id/members
GET /v1/permissions
GET /v1/tenants/:id/permissions/check?permission=member.invite
GET /v1/tenants/:id/api-keys
POST /v1/tenants/:id/api-keys
POST /v1/api-keys/:id/rotate
POST /v1/api-keys/:id/revoke
POST /v1/usage/events
GET /v1/tenants/:id/usage/events
GET /v1/tenants/:id/usage/summary
GET /v1/tenants/:id/billing/providers
POST /v1/tenants/:id/billing/providers
POST /v1/billing/connect/stripe
POST /v1/billing/connect/razorpay
POST /v1/billing/connect/dodo
POST /v1/billing/mappings
GET /v1/billing/sync-logs?tenant_id=seqn
POST /v1/billing/sync-logs/:id/retry
POST /v1/export/all
GET /v1/exports/:id
GET /v1/exports/:id/download

API key create and rotate return the raw secretKey once. List/read responses return only safe metadata such as id, prefix, scopes, timestamps, and revocation state. Usage passbook events are append-only and deduplicate per tenant with idempotencyKey.

GET /v1/exports/:id returns a sanitized snapshot record. GET /v1/exports/:id/download returns JSON or CSV according to the snapshot format, or ?format=json|csv when a caller wants an alternate serialization. Secret-shaped fields such as raw API keys, hashes, tokens, ciphertext, and webhook secrets are stripped.

Billing providers are handoff records only. SEQN Auth records what happened, queues sync logs, maps usage events to provider items, and exposes sandbox-safe adapter status based on the presence of provider env vars. Stripe, Razorpay, and Dodo Payments remain the systems that charge, invoice, tax, refund, and manage subscriptions.

Provider env names:

STRIPE_SECRET_KEY
RAZORPAY_KEY_ID
RAZORPAY_KEY_SECRET
DODO_PAYMENTS_API_KEY

Webhook delivery APIs

GET /v1/webhook-deliveries?organization_slug=seqn&endpoint_id=wh_...&status=retrying&event_type=usage_event.created
POST /v1/webhook-deliveries/:id/retry?organization_slug=seqn

Delivery logs are sanitized and never include whsec_* signing secrets. Retry resets a failed/retrying delivery to pending with a new next-attempt timestamp; actual dispatch still goes through the delivery worker/process path.

Manual subscription APIs

Payment collection is not built in. These endpoints manage plan, seat, status, and usage state for self-hosted operations.

GET /v1/subscription-plans
POST /v1/subscription-plans
PATCH /v1/subscription-plans/:id
GET /v1/subscription?organization_slug=seqn
PATCH /v1/subscription?organization_slug=seqn
GET /v1/usage?organization_slug=seqn
POST /v1/usage-events

POST /v1/usage-events accepts either the hosted session cookie or Authorization: Bearer sk_live_... for backend metering.

Mutating project/user/webhook and usage routes enforce subscription state. Inactive, cancelled, expired, or over-limit organizations receive 402 errors with codes such as subscription_inactive or subscription_limit_exceeded. This is payment logic only; checkout and invoices are intentionally outside the MVP.