Authentication

ObjectOS uses the ObjectStack authentication plugin, powered by Better Auth. Authentication is project-local: each project has its own identity tables and session scope.

What is supported

Depending on the packaged application and enabled settings, ObjectOS can support:

email/password sign-in;
session management;
password reset and email verification;
social OAuth providers such as Google, GitHub, Microsoft, and Apple;
enterprise OIDC/SSO such as Okta, Entra ID, Keycloak, and Ping;
two-factor authentication;
passkeys/WebAuthn;
magic links;
phone number sign-in with SMS OTP (opt-in);
CLI/browser device flow.

Enable phone-number authentication via the auth.plugins.phoneNumber setting. Once on:

POST /sign-in/phone-number accepts phone + password;
SMS OTP covers sign-in verification and self-service password reset, with per-number cooldowns, rolling-hour caps, and per-IP rate limits;
sys_user gains unique phone_number and phone_number_verified columns; phone-only accounts get a placeholder email.

SMS delivery is provided by @objectstack/plugin-sms with Aliyun SMS, Twilio, or a dev log fallback, configured through the sms settings namespace. Message bodies containing OTP codes are never persisted or logged. Notifications can also target the sms channel via notify(channels: ['sms']).

Admin user management (ObjectStack 14.3+)

Platform admins can provision accounts without the email invite flow:

POST /api/v1/auth/admin/create-user creates a user directly, with an optional one-time password (returned once, never persisted). The must_change_password flag forces rotation at first sign-in (403 PASSWORD_EXPIRED until changed).
POST /api/v1/auth/admin/import-users bulk-imports rows / CSV / XLSX (max 500 rows per request) with dry-run and upsert-by-email-or-phone modes; existing users never get their passwords reset. Since 16.0 the default passwordPolicy is 'auto': rows with a deliverable channel (real email + wired email service, or phone + SMS invite path) are invited, and only unreachable rows get a temporary password (returned once, must_change_password). Callers that relied on the old identity-only default must now pass passwordPolicy: 'none' explicitly; per-row outcomes are on rows[].delivery with a summary.delivery breakdown.

Required secret

Set:

OS_AUTH_SECRET=replace-with-a-strong-random-secret

ObjectOS derives a stable per-project secret from this value and the project environment id. This means:

sessions survive container restarts;
tokens from one project cannot be reused on another project;
rotating OS_AUTH_SECRET invalidates sessions.

See Environment variables for the full list of auth-related settings, including the legacy AUTH_SECRET alias.

Session isolation

In multi-project deployments, cookies are scoped to the project hostname. ObjectOS intentionally avoids broad root-domain cookies for project sessions. This prevents a session from leaking across customer projects.

Configure provider credentials through environment variables or system settings, depending on how the application package exposes auth configuration.

Provider callback URLs depend on the provider type. ObjectStack exposes two distinct callback paths and they are not interchangeable:

Provider type	Callback path
Built-in social (Google, GitHub, Microsoft, Apple, …)	`/api/v1/auth/callback/<provider>`
Generic OIDC / OAuth2 (Okta, Entra ID, Keycloak, Ping, …)	`/api/v1/auth/oauth2/callback/<provider>`

Examples:

https://crm.example.com/api/v1/auth/callback/google
https://crm.example.com/api/v1/auth/callback/microsoft
https://crm.example.com/api/v1/auth/oauth2/callback/okta
https://crm.example.com/api/v1/auth/oauth2/callback/entra

Configure the matching redirect URI in the identity provider's application registration before enabling the provider in ObjectOS.

Enterprise OIDC/SSO

OIDC providers are registered as generic OAuth2 providers and use the /api/v1/auth/oauth2/callback/<provider> path. A typical configuration requires:

Field	Description
Provider id	Stable id such as `okta` or `entra` (used in the callback URL)
Display name	Button label shown to users
Discovery URL	`.well-known/openid-configuration` endpoint
Client id	Application client id from the identity provider
Client secret	Secret stored in environment or encrypted settings
Scopes	Usually `openid email profile`

For customer deployments, prefer OIDC discovery URLs over manually configured authorization/token/userinfo endpoints.

Platform SSO

In cloud-connected deployments, ObjectOS can use the control-plane login as a platform SSO provider. A builder who is already signed in to the control plane can be provisioned into a project runtime without creating a separate project-local account.

This requires the control plane and ObjectOS to share the same OS_AUTH_SECRET base secret. Disable platform SSO only when the customer wants every project to own a completely separate login boundary.

Operational checks

Before production:

confirm expired tokens return 401;
confirm logout revokes the active session;
confirm password reset revokes other sessions if required by policy;
confirm callback URLs match the public project domain;
confirm trusted origins include only approved domains;
confirm OS_AUTH_SECRET is stored in a secret manager, not in source.

Next steps

Authentication establishes who a user is. To control what they can access once signed in, see Permissions. For non-browser clients and machine-to-machine access, see API access.

On this page