Auth schema — API Protocol property reference

Defines the standard API contracts for Identity, Session Management, and Access Control.

Authentication Service Protocol

Defines the standard API contracts for Identity, Session Management, and Access Control.

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

TypeScript Usage

import { AuthProvider, LoginRequestSchema, LoginType, RefreshTokenRequestSchema, RegisterRequestSchema, SessionSchema, SessionResponseSchema, SessionUserSchema, UserProfileResponseSchema } from '@objectstack/spec/api';
import type { AuthProvider, LoginRequest, LoginType, RefreshTokenRequest, RegisterRequest, Session, SessionResponse, SessionUser, UserProfileResponse } from '@objectstack/spec/api';

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

AuthProvider

Allowed Values

local
google
github
microsoft
ldap
saml

LoginRequest

Properties

Property	Type	Required	Description
type	`Enum<'email' \| 'username' \| 'phone' \| 'magic-link' \| 'social'>`	optional (default: `"email"`)	Login method
email	`string`	optional	Required for email/magic-link
username	`string`	optional	Required for username login
password	`string`	optional	Required for password login
provider	`string`	optional	Required for social (google, github)
redirectTo	`string`	optional	Redirect URL after successful login

LoginType

Allowed Values

email
username
phone
magic-link
social

RefreshTokenRequest

Properties

Property	Type	Required	Description
refreshToken	`string`	✅	Refresh token

RegisterRequest

Properties

Property	Type	Required
email	`string`	✅
password	`string`	✅
name	`string`	✅
image	`string`	optional

Session

Properties

Property	Type	Required
id	`string`	✅
expiresAt	`string`	✅
token	`string`	optional
ipAddress	`string`	optional
userAgent	`string`	optional
userId	`string`	✅

SessionResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅	Operation success status
error	`{ code: Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| …>; declaredCode?: string; message: string; userMessage?: string; … }`	optional	Error details if success is false
meta	`{ timestamp: string; duration?: integer; requestId?: string; traceId?: string }`	optional	Response metadata
data	`{ session: object; user: object; token?: string }`	✅

Nested Shape: `SessionResponse.error`

Property	Type	Required	Description
code	`Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| …>`	✅	Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode	`string`	optional	The producer-declared code, verbatim, when it is not a member of the closed `code` vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message	`string`	✅	Readable error message
userMessage	`string`	optional	Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces `message`.
refusal	`true`	optional	Producer-declared: the 5xx this envelope carries is a deliberate refusal whose `message` is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose `message` is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — `true` is the only value.
category	`string`	optional	Error category (e.g. validation, authorization)
httpStatus	`integer`	optional	HTTP status of the response carrying this error
details	`any`	optional	Additional error context (e.g. field validation errors)
requestId	`string`	optional	Request ID for tracking

Nested Shape: `SessionResponse.meta`

Property	Type	Required	Description
timestamp	`string`	✅
duration	`integer`	optional	Server-side processing duration in milliseconds
requestId	`string`	optional
traceId	`string`	optional

Nested Shape: `SessionResponse.data`

Property	Type	Required	Description
session	`{ id: string; expiresAt: string; token?: string; ipAddress?: string; … }`	✅	Active Session Info
user	`{ id: string; email: string; emailVerified?: boolean; name: string; … }`	✅	Current User Details
token	`string`	optional	Bearer token if not using cookies

SessionUser

Properties

Property	Type	Required	Description
id	`string`	✅	User ID
email	`string`	✅	Email address
emailVerified	`boolean`	optional (default: `false`)	Is email verified?
name	`string`	✅	Display name
image	`string \| null`	optional	Avatar URL
username	`string`	optional	Username (optional)
roles	`string[]`	optional (default: `[]`)	Assigned role IDs
tenantId	`string`	optional	Current tenant ID
language	`never`	optional	[REMOVED] `SessionUser.language` was removed in @objectstack/spec 17.4.0 (ADR-0049 enforce-or-remove) — it was declared with a permanent default of `'en'` and never produced by any session endpoint nor read by any client, so a reader keying on it saw a constant, not the user's language. Delete the key. Read the signed-in user's language from `GET /auth/me/localization` (`locale`: the user's own `sys_user.locale` when set → the request's `Accept-Language` → the deployment default).
timezone	`string`	optional	Preferred timezone
createdAt	`string`	optional
updatedAt	`string`	optional

UserProfileResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅	Operation success status
error	`{ code: Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| …>; declaredCode?: string; message: string; userMessage?: string; … }`	optional	Error details if success is false
meta	`{ timestamp: string; duration?: integer; requestId?: string; traceId?: string }`	optional	Response metadata
data	`{ id: string; email: string; emailVerified?: boolean; name: string; … }`	✅

Nested Shape: `UserProfileResponse.error`

Property	Type	Required	Description
code	`Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| …>`	✅	Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode	`string`	optional	The producer-declared code, verbatim, when it is not a member of the closed `code` vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message	`string`	✅	Readable error message
userMessage	`string`	optional	Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces `message`.
refusal	`true`	optional	Producer-declared: the 5xx this envelope carries is a deliberate refusal whose `message` is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose `message` is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — `true` is the only value.
category	`string`	optional	Error category (e.g. validation, authorization)
httpStatus	`integer`	optional	HTTP status of the response carrying this error
details	`any`	optional	Additional error context (e.g. field validation errors)
requestId	`string`	optional	Request ID for tracking

Nested Shape: `UserProfileResponse.meta`

Property	Type	Required	Description
timestamp	`string`	✅
duration	`integer`	optional	Server-side processing duration in milliseconds
requestId	`string`	optional
traceId	`string`	optional

Nested Shape: `UserProfileResponse.data`

Property	Type	Required	Description
id	`string`	✅	User ID
email	`string`	✅	Email address
emailVerified	`boolean`	optional (default: `false`)	Is email verified?
name	`string`	✅	Display name
image	`string \| null`	optional	Avatar URL
username	`string`	optional	Username (optional)
roles	`string[]`	optional (default: `[]`)	Assigned role IDs
tenantId	`string`	optional	Current tenant ID
language	`never`	optional	[REMOVED] `SessionUser.language` was removed in @objectstack/spec 17.4.0 (ADR-0049 enforce-or-remove) — it was declared with a permanent default of `'en'` and never produced by any session endpoint nor read by any client, so a reader keying on it saw a constant, not the user's language. Delete the key. Read the signed-in user's language from `GET /auth/me/localization` (`locale`: the user's own `sys_user.locale` when set → the request's `Accept-Language` → the deployment default).
timezone	`string`	optional	Preferred timezone
createdAt	`string`	optional
updatedAt	`string`	optional

Auth schema — API Protocol property reference

On this page