ObjectStackObjectStack

Auth Endpoints

Auth Endpoints protocol schemas

Authentication Endpoint Specification

Defines the canonical HTTP endpoints for the authentication service. Based on better-auth v1.4.18 endpoint conventions.

NOTE: ObjectStack's auth implementation uses better-auth library which has established endpoint conventions. This spec documents those conventions as the canonical API contract.

Source: packages/spec/src/api/auth-endpoints.zod.ts

TypeScript Usage

import { AuthEndpointSchema, AuthFeaturesConfigSchema, AuthProviderInfoSchema, DeviceRequestResponseSchema, DeviceTokenResponseSchema, EmailPasswordConfigPublicSchema, GetAuthConfigResponseSchema } from '@objectstack/spec/api';
import type { AuthEndpoint, AuthFeaturesConfig, AuthProviderInfo, DeviceRequestResponse, DeviceTokenResponse, EmailPasswordConfigPublic, GetAuthConfigResponse } from '@objectstack/spec/api';

// Validate data
const result = AuthEndpointSchema.parse(data);

AuthEndpoint

Properties

PropertyTypeRequiredDescription
signInEmail{ method: 'POST'; path: '/sign-in/email'; description: 'Sign in with email and password' }✅
signUpEmail{ method: 'POST'; path: '/sign-up/email'; description: 'Register new user with email and password' }✅
signOut{ method: 'POST'; path: '/sign-out'; description: 'Sign out current user' }✅
getSession{ method: 'GET'; path: '/get-session'; description: 'Get current user session' }✅
forgetPassword{ method: 'POST'; path: '/forget-password'; description: 'Request password reset email' }✅
resetPassword{ method: 'POST'; path: '/reset-password'; description: 'Reset password with token' }✅
sendVerificationEmail{ method: 'POST'; path: '/send-verification-email'; description: 'Send email verification link' }✅
verifyEmail{ method: 'GET'; path: '/verify-email'; description: 'Verify email with token' }✅

AuthFeaturesConfig

Properties

PropertyTypeRequiredDescription
twoFactorboolean✅Two-factor authentication enabled
passkeysneveroptional[REMOVED] features.passkeys was removed from GET /api/v1/auth/config in @objectstack/spec 17 (#7481, ADR-0049) — it was served from introduction and consumed by nothing: no login UI in any client reads it, and no better-auth passkey plugin is wired behind it, so a deployer who set plugins.passkeys: true flipped a switch that changed no behaviour anywhere. Delete the key. There is no replacement flag to read: passkey sign-in is not a capability this platform offers yet. It returns to this payload in the change that ships the login UI (objectui#4179), classified in PUBLIC_AUTH_FEATURES again at that point — do not re-add it ahead of a consumer.
magicLinkneveroptional[REMOVED] features.magicLink was removed from GET /api/v1/auth/config in @objectstack/spec 17 (#7481, ADR-0049) — the ADVERTISEMENT was inert, not the capability: no client renders a magic-link sign-in affordance off this flag, so it only told a deployer that a UI existed when none did. Delete the key. The server side is unchanged and still yours to call: AuthPluginConfig.plugins.magicLink wires better-auth's magic-link plugin, and /api/v1/auth/magic-link/send + /magic-link/verify answer exactly as before — drive them from your own UI, or wait for objectui#4179, which restores this flag along with the login UI that reads it.
organizationboolean✅Multi-tenant organization support enabled
ssoEnforcedbooleanoptionalSSO-only login enforced: the UI hides the local password form + self-registration (a break-glass "use a password" link remains)
phoneNumberbooleanoptionalPhone-number sign-in enabled (phone + password, #2766 V1.5)
phoneNumberOtpbooleanoptionalPhone-number OTP sign-in and self-service password reset available — requires the phoneNumber plugin plus a deliverable SMS service (#2780)

AuthProviderInfo

Properties

PropertyTypeRequiredDescription
idstring✅Provider ID (e.g., google, github, microsoft, okta)
namestring✅Display name (e.g., Google, GitHub)
enabledboolean✅Whether this provider is enabled
typeEnum<'social' | 'oidc'>✅Provider type

DeviceRequestResponse

Properties

PropertyTypeRequiredDescription
codestring✅Short-lived device code used for polling
verificationUrlstring✅URL the user should open in a browser
expiresAtstring✅ISO timestamp when the code expires
intervalnumber✅Recommended polling interval in seconds

DeviceTokenResponse

Union Options

This schema accepts one of the following structures:

Option 1

Properties

PropertyTypeRequiredDescription
status'pending'✅

Option 2

Properties

PropertyTypeRequiredDescription
status'approved'✅
tokenstring✅Bearer token to store in credentials file
user{ id: string; email: string; name?: string }✅

Option 3

Properties

PropertyTypeRequiredDescription
status'expired'✅

EmailPasswordConfigPublic

Properties

PropertyTypeRequiredDescription
enabledboolean✅Whether email/password auth is enabled
disableSignUpbooleanoptionalWhether new user registration is disabled
requireEmailVerificationbooleanoptionalWhether email verification is required

GetAuthConfigResponse

Properties

PropertyTypeRequiredDescription
emailPassword{ enabled: boolean; disableSignUp?: boolean; requireEmailVerification?: boolean }✅Email/password authentication config
socialProviders{ id: string; name: string; enabled: boolean; type: Enum<'social' | 'oidc'> }[]✅Available social/OAuth providers
features{ twoFactor: boolean; organization: boolean; ssoEnforced?: boolean; phoneNumber?: boolean; … }✅Enabled authentication features

On this page

TypeScript UsageAuthEndpointPropertiesAuthFeaturesConfigPropertiesAuthProviderInfoPropertiesDeviceRequestResponsePropertiesDeviceTokenResponseUnion OptionsOption 1PropertiesOption 2PropertiesOption 3PropertiesEmailPasswordConfigPublicPropertiesGetAuthConfigResponseProperties