Auth

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?: number; 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`.
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.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`	optional	Avatar URL
username	`string`	optional	Username (optional)
roles	`string[]`	optional (default: `[]`)	Assigned role IDs
tenantId	`string`	optional	Current tenant ID
language	`string`	optional (default: `"en"`)	Preferred language
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?: number; 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`.
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.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`	optional	Avatar URL
username	`string`	optional	Username (optional)
roles	`string[]`	optional (default: `[]`)	Assigned role IDs
tenantId	`string`	optional	Current tenant ID
language	`string`	optional (default: `"en"`)	Preferred language
timezone	`string`	optional	Preferred timezone
createdAt	`string`	optional
updatedAt	`string`	optional

On this page