SEQN Auth API Contract

This contract describes the Clerk-like MVP endpoints consumed by @seqn/auth-js. It excludes email delivery and payment collection.

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://accounts.seqn.in/sign-in",
    "signUpUrl": "https://accounts.seqn.in/sign-up",
    "afterSignInUrl": "https://app.seqn.in",
    "afterSignUpUrl": "https://app.seqn.in"
  },
  "oidc": {
    "issuer": "https://auth.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.

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.
• 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, Authentik tokens, or payment-provider secrets.

Public signup workspace behavior

Hosted /sign-up and /sign-in both hand off to Authentik/Google OIDC. 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 Authentik 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

Invitation create returns invitationToken and inviteLink once. SMTP is skipped, so admins copy that link manually.

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.