バージョン: 🚧 Canary

🔍 Authentication Schemas

Authentication schemas provide JSON Schema definitions for authentication data validation in Nodeblocks applications. These schemas ensure secure authentication flows and provide clear contracts for authentication-related API endpoints.

🎯 Overview

Authentication schemas are designed to:

Validate authentication data before processing
Support multiple auth methods (OAuth, email/password)
Ensure secure authentication with proper validation
Enable email verification workflows
Support device fingerprinting for enhanced security

📋 Authentication Schema Types

Provider Authentication Schemas

OAuth and third-party authentication validation.

Credentials Authentication Schemas

Email/password authentication validation.

Identity Schemas

Flexible authentication with support for multiple methods.

Email Verification Schemas

Email verification and confirmation workflows.

🔧 Available Authentication Schemas

`passwordSchema`

Password validation schema with security requirements and pattern matching.

Purpose: Serves as a base schema for password validation, used by other authentication schemas

Schema Details:

Type: object
Required Fields: None
Additional Properties: false
Properties:
- password: string — 8-24 chars; at least one lowercase letter and one number; allows ?/_-

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { passwordSchema } = schemas;

const validate = ajv.compile(passwordSchema as SchemaDefinition);
const isValid = validate({ password: 'securePass123' });

`providerSchema`

Provider authentication schema for OAuth and third-party authentication.

Purpose: Validates OAuth provider authentication data

Schema Details:

Type: object
Required Fields: provider, providerId
Additional Properties: false (strict validation)
Properties:
- provider: string - OAuth provider name
- providerId: string - Provider-specific user ID

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { providerSchema } = schemas;
const validate = ajv.compile(providerSchema as SchemaDefinition);
const isValid = validate({ provider: 'google', providerId: '12345' });

`credentialsSchema`

Credentials authentication schema for email/password authentication.

Purpose: Validates email/password authentication data

Schema Details:

Type: object
Required Fields: email, password
Additional Properties: false (strict validation)
Properties:
- email: string - Identity email address
- emailVerified: boolean - Email verification status (default: false)
- password: string - User password

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { credentialsSchema } = schemas;
const validate = ajv.compile(credentialsSchema as SchemaDefinition);
const isValid = validate({ email: 'identity@example.com', password: 'password123' });

`changePasswordSchema`

Password change schema with current and new password validation for user accounts.

Purpose: Validates password change requests with security requirements

Schema Details:

Type: object
Required Fields: password, newPassword
Additional Properties: false (strict validation)
Parameters: identityId (path parameter)
Content-Type: application/json
Request Body: required
Properties:
- password: string - Current password for verification
- newPassword: string - New password with security requirements

New Password Requirements:

Length: 8-24 characters
Pattern: Must contain at least one lowercase letter and one number
Allowed characters: Letters, numbers, and special characters (?/_-)
Validation: Regex pattern enforces security requirements for newPassword
Identity ID: Required as path parameter for identity identification

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { changePasswordSchema } = schemas;

// Apply to feature composition:
export const changePasswordFeature = compose(changePasswordSchema, changePasswordRoute);

`completePasswordResetSchema`

Password reset completion schema with password validation for account recovery.

Purpose: Validates password reset completion requests with security requirements

Schema Details:

Type: object
Required Fields: password
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required
Properties:
- password: string - New password with security requirements

Password Requirements:

Length: 8-24 characters
Pattern: Must contain at least one lowercase letter and one number
Allowed characters: Letters, numbers, and special characters (?/_-)
Validation: Inherits from passwordSchema security requirements
Workflow: Used in password reset workflow after receiving reset link

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { completePasswordResetSchema } = schemas;

// Apply to feature composition:
export const completePasswordResetFeature = compose(completePasswordResetSchema, completePasswordResetRoute);

`activateSchema`

Identity activation schema with identity validation for account activation.

Purpose: Validates identity activation requests with identity ID validation

Schema Details:

Type: object
Required Fields: identityId
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required
Properties:
- identityId: string - User identity identifier for activation

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { activateSchema } = schemas;

// Apply to feature composition:
export const activateFeature = compose(activateSchema, activateRoute);

`deactivateSchema`

Identity deactivation schema with identity validation for account deactivation.

Purpose: Validates identity deactivation requests with identity ID validation

Schema Details:

Type: object
Required Fields: identityId
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required
Properties:
- identityId: string - User identity identifier for deactivation

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { deactivateSchema } = schemas;

// Apply to feature composition:
export const deactivateFeature = compose(deactivateSchema, deactivateRoute);

`identitySchema`

Identity schema that supports both provider and credentials authentication.

Purpose: Validates authentication data with support for multiple auth methods

Schema Details:

Type: object
Required Fields: Either provider+providerId OR email+password
Additional Properties: false (strict validation)
Validation: Requires either provider+providerId OR email+password
Content-Type: application/json
Request Body: required

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { identitySchema } = schemas;

const identitySchema = identitySchema({});
const validate = ajv.compile(identitySchema.schemas as SchemaDefinition);

// Provider auth
const isValidProvider = validate({ provider: 'google', providerId: '12345' });

// Credentials auth
const isValidCredentials = validate({ email: 'identity@example.com', password: 'password123' });

`loginWithCredentialsSchema`

Purpose: Validates login request data with optional device fingerprinting

Schema Details:

Type: object
Required Fields: email, password
Optional Fields: fingerprint
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { loginWithCredentialsSchema } = schemas;

const loginSchema = loginWithCredentialsSchema({});
const validate = ajv.compile(loginSchema.schemas as SchemaDefinition);
const isValid = validate({
  email: 'identity@example.com',
  password: 'password123',
  fingerprint: 'device-fingerprint-hash'
});

`resendMfaCodeSchema`

MFA code resend schema with token validation for authentication.

Purpose: Validates MFA code resend requests for users who need a new verification code

Schema Details:

Type: object
Required Fields: token
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required
Properties:
- token: string - MFA challenge token from initial login attempt

Use Cases:

User didn't receive initial MFA code email
MFA code expired before user could enter it
Email delivery delay or failure
User accidentally deleted email

Security Features:

Invalidates previous MFA token
Generates new MFA code for security
Issues new MFA token
Maintains token-based verification flow

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { resendMfaCodeSchema } = schemas;

// Apply to feature composition:
export const resendMfaCodeFeature = compose(resendMfaCodeSchema, resendMfaCodeRoute);

// Example valid request:
const validRequest = {
  token: 'encrypted-mfa-challenge-token'
};

Request Example:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Example (Success):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

`verifyMfaCodeSchema`

MFA code verification schema with token and code validation.

Purpose: Validates MFA code verification requests with MFA token and user-provided code

Schema Details:

Type: object
Required Fields: token, code
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required
Properties:
- token: string - MFA challenge token returned from login endpoint
- code: string - User-provided MFA verification code (from email)

Workflow:

User attempts login with credentials
System sends MFA code via email and returns MFA token
User receives MFA code in email
User submits MFA token and code for verification
System validates code and returns access/refresh tokens

Security Features:

Token-based verification prevents replay attacks
One-time tokens invalidated after use
Time-limited tokens prevent stale code usage
Strict schema validation

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { verifyMfaCodeSchema } = schemas;

// Apply to feature composition:
export const verifyMfaCodeFeature = compose(verifyMfaCodeSchema, verifyMfaCodeRoute);

// Example valid request:
const validRequest = {
  token: 'encrypted-mfa-challenge-token',
  code: '123456'
};

Request Example:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "code": "123456"
}

Response Example (Success):

{
  "id": "identity-uuid",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

`loginWithOnetimeTokenSchema`

One-time token login schema with token validation for secure authentication.

Purpose: Validates one-time token login requests for passwordless authentication

Schema Details:

Type: object
Required Fields: token
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required
Properties:
- token: string - One-time authentication token (typically from magic link)

Use Cases:

Magic link authentication
Email-based passwordless login
Secure account access without password
Time-limited authentication tokens

Security Features:

Token must have type: 'onetime'
Token must have target: 'login'
Tokens are one-time use (invalidated after login)
Tokens include identity ID for user lookup
Token validation includes fingerprint and request info

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { loginWithOnetimeTokenSchema } = schemas;

// Apply to feature composition:
export const loginWithOnetimeTokenFeature = compose(
  loginWithOnetimeTokenSchema, 
  loginWithOnetimeTokenRoute
);

// Example valid request:
const validRequest = {
  token: 'encrypted-onetime-authentication-token'
};

Request Example:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Example (Success):

{
  "id": "identity-uuid",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Typical Flow:

User requests magic link (separate endpoint)
System generates one-time token with target: 'login'
System sends magic link to user's email
User clicks link and submits token
System validates token and returns authentication tokens

`registerCredentialsSchema`

Identity registration schema with email/password or token/password validation.

Purpose: Schema validator for identity registration requests

Schema Details:

Type: object
Required Fields: password (always required)
Optional Fields: email, token
Validation: Requires either email+password OR token+password
Content-Type: application/json
Request Body: required

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { registerCredentialsSchema } = schemas;

const registerSchema = registerCredentialsSchema({});
const validate = ajv.compile(registerSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  email: 'identity@example.com', 
  password: 'password123' 
});

`sendVerificationEmailSchema`

JSON Schema for validating send verification email requests.

Purpose: Validates the request body for the send verification email endpoint

Schema Details:

Type: object
Required Fields: None (all fields optional)
Additional Properties: false (strict validation)
Parameters: identityId (path parameter)
Content-Type: application/json
Request Body: required
Properties:
- fingerprint?: string - Optional device fingerprinting

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { sendVerificationEmailSchema } = schemas;

const verificationSchema = sendVerificationEmailSchema({});
const validate = ajv.compile(verificationSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  fingerprint: 'device-fingerprint-hash' 
});

`confirmEmailSchema`

Email confirmation schema with token validation for email verification.

Purpose: Schema validator for email confirmation requests

Schema Details:

Type: object
Required Fields: token
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required
Properties:
- token: string - Verification token from email

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { confirmEmailSchema } = schemas;

const confirmSchema = confirmEmailSchema({});
const validate = ajv.compile(confirmSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  token: 'verification-token-123' 
});

`changeEmailSchema`

Email change schema with identity validation for user email updates.

Purpose: Schema validator for email change requests

Schema Details:

Type: object
Required Fields: email
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required
Parameters: identityId (path parameter)
Properties:
- email: string - New email address for identity account

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { changeEmailSchema } = schemas;

const changeEmailSchema = changeEmailSchema({});
const validate = ajv.compile(changeEmailSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  email: 'newemail@example.com' 
});

`checkTokenSchema`

Token validation schema with required token and optional target parameters.

Purpose: Schema validator for token validation requests

Schema Details:

Type: object
Required Fields: token
Optional Fields: target
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required
Properties:
- token: string - JWT token string to validate
- target?: string - Target context for token validation (e.g., 'confirm-email', 'change-email')

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { checkTokenSchema } = schemas;

const checkTokenSchema = checkTokenSchema({});
const validate = ajv.compile(checkTokenSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  token: 'jwt-token-here',
  target: 'confirm-email'
});

`confirmNewEmailSchema`

New email confirmation schema with token validation for email change verification.

Purpose: Schema validator for new email confirmation requests

Schema Details:

Type: object
Required Fields: token
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required
Properties:
- token: string - Verification token from new email

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { confirmNewEmailSchema } = schemas;

const confirmNewEmailSchema = confirmNewEmailSchema({});
const validate = ajv.compile(confirmNewEmailSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  token: 'verification-token-123' 
});

`sendResetPasswordLinkEmailSchema`

Password reset email schema with email validation for password recovery.

Purpose: Schema validator for password reset email requests

Schema Details:

Type: object
Required Fields: email
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required
Properties:
- email: string - User email address for password reset

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { sendResetPasswordLinkEmailSchema } = schemas;

const resetPasswordSchema = sendResetPasswordLinkEmailSchema({});
const validate = ajv.compile(resetPasswordSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  email: 'identity@example.com' 
});

`refreshTokenSchema`

Token refresh schema with refresh token validation for token renewal requests.

Purpose: Schema validator for token refresh requests

Schema Details:

Type: object
Required Fields: refreshToken
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required
Properties:
- refreshToken: string - Refresh token for authentication renewal

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { refreshTokenSchema } = schemas;

// Apply to feature composition:
export const refreshTokenFeature = compose(refreshTokenSchema, refreshTokenRoute);

`deleteRefreshTokensSchema`

Refresh token deletion schema with identity path parameter validation.

Purpose: Schema validator for refresh token deletion requests

Schema Details:

Type: object
Required Fields: identityId (path parameter)
Additional Properties: false (strict validation)
Parameters: identityId path parameter

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { deleteRefreshTokensSchema } = schemas;

// Apply to feature composition:
export const deleteRefreshTokensFeature = compose(deleteRefreshTokensSchema, deleteRefreshTokensRoute);

Authentication Domain Overview - Authentication domain overview

🎯 Overview​

📋 Authentication Schema Types​

Provider Authentication Schemas​

Credentials Authentication Schemas​

Identity Schemas​

Email Verification Schemas​

🔧 Available Authentication Schemas​

passwordSchema​

providerSchema​

credentialsSchema​

changePasswordSchema​

completePasswordResetSchema​

activateSchema​

deactivateSchema​

identitySchema​

loginWithCredentialsSchema​

resendMfaCodeSchema​

verifyMfaCodeSchema​

loginWithOnetimeTokenSchema​

registerCredentialsSchema​

sendVerificationEmailSchema​

confirmEmailSchema​

changeEmailSchema​

checkTokenSchema​

confirmNewEmailSchema​

sendResetPasswordLinkEmailSchema​

refreshTokenSchema​

deleteRefreshTokensSchema​

🔗 Related Documentation​

🎯 Overview

📋 Authentication Schema Types

Provider Authentication Schemas

Credentials Authentication Schemas

Identity Schemas

Email Verification Schemas

🔧 Available Authentication Schemas

`passwordSchema`

`providerSchema`

`credentialsSchema`

`changePasswordSchema`

`completePasswordResetSchema`

`activateSchema`

`deactivateSchema`

`identitySchema`

`loginWithCredentialsSchema`

`resendMfaCodeSchema`

`verifyMfaCodeSchema`

`loginWithOnetimeTokenSchema`

`registerCredentialsSchema`

`sendVerificationEmailSchema`

`confirmEmailSchema`

`changeEmailSchema`

`checkTokenSchema`

`confirmNewEmailSchema`

`sendResetPasswordLinkEmailSchema`

`refreshTokenSchema`

`deleteRefreshTokensSchema`

🔗 Related Documentation