Authentication Service

The Authentication Service provides secure user authentication and authorization capabilities across your organization’s ecosystem. It manages user identity verification, session handling, and supports multiple authentication methods including password, one-time passwords (OTP), OAuth providers (Google, Microsoft), Azure AD, OAuth, and SAML SSO.

Base URL

All endpoints are prefixed with /api/v1

Authentication

Most endpoints require authentication via Bearer token:

Authorization: Bearer YOUR_TOKEN

Internal endpoints use scoped token authentication for service-to-service communication with specific scopes:

PASSWORD_RESET - For password reset operations
TOKEN_REFRESH - For token refresh operations
FETCH_CONFIG - For configuration updates

Architecture Overview

The Authentication Service is built on a Node.js backend with MongoDB for data persistence and Redis for session management. The service implements a container-based dependency injection pattern using InversifyJS for better modularity and testability. Key components that the Auth Service integrates with:

IAM Service - Manages user and organization information
Configuration Manager - Stores authentication provider configurations
Communication Service - Handles email delivery for password resets and OTP
Redis - Manages authentication sessions and temporary tokens

Authentication Flow Process

The Auth Service employs a multi-step session-based authentication flow:

Authentication Initialization
- Client calls the /userAccount/initAuth endpoint with an email
- Server validates the email and creates a temporary session in Redis
- Server returns a session token in the x-session-token response header along with available authentication methods
Authentication Steps
- Client calls /userAccount/authenticate with the session token in the x-session-token header
- Client provides chosen authentication method and credentials
- The method must be one the organization allows for the current step. Any other method is refused with 400 before any password or code is checked
- If multi-factor authentication is configured, the server returns information about the next step
- Client repeats the authentication step with appropriate credentials until all required steps are completed
- Every step must be completed by the same account. A later step completed for a different account (for example a different Google, Microsoft, OAuth or SAML identity) is refused, and no account is created for it
Token Issuance
- After successful authentication, the server issues access and refresh tokens
- The Redis session is cleared
- Client stores tokens for subsequent API calls

Here’s a sequence diagram of the flow:

Data Models

OrgAuthConfig Schema

interface IOrgAuthConfig extends Document {
  orgId: Types.ObjectId;
  domain?: string;
  authSteps: {
    order: number;
    allowedMethods: {
      type: 'samlSso' | 'otp' | 'password' | 'google' | 'microsoft' | 'azureAd' | 'oauth';
    }[];
  }[];
  isDeleted?: boolean;
  createdAt?: Date;
  updatedAt?: Date;
}

UserCredentials Schema

interface IUserCredentials extends Document {
  userId?: string | null;
  orgId: string;
  ipAddress: string;
  otpValidity?: number;
  hashedOTP?: string;
  hashedPassword?: string;
  forceNewPasswordGeneration: boolean;
  wrongCredentialCount: number;
  isBlocked: boolean;
  isDeleted: boolean;
  createdAt?: Date;
  updatedAt?: Date;
}

UserActivities Schema

interface IUserActivity extends Document {
  email: string;
  userId: Types.ObjectId;
  orgId?: Types.ObjectId;
  activityType:
    | 'LOGIN'
    | 'LOGOUT'
    | 'LOGIN_ATTEMPT'
    | 'OTP_GENERATE'
    | 'WRONG_OTP'
    | 'WRONG_PASSWORD'
    | 'REFRESH_TOKEN';
  loginMode?:
    | 'OTP'
    | 'PASSWORD'
    | 'AUTH SERVICE'
    | 'GOOGLE OAUTH'
    | 'MICROSOFT OAUTH'
    | 'AZUREAD OAUTH'
    | 'OAUTH'
    | 'SSO';
  ipAddress: string;
  isDeleted?: boolean;
  createdAt?: Date;
  updatedAt?: Date;
}

Session Data

interface SessionData {
  token?: string;
  userId: string;
  email: string;
  orgId: string;
  authConfig: IAuthStep[];
  currentStep: number;
  isAuthenticated?: boolean;
  [key: string]: any; // Allows additional properties
}

Session Management with Redis

The Auth Service uses Redis to store temporary session data during the authentication process:

Sessions are identified by a unique UUID token
The x-session-token header is used to track the session across requests
Sessions expire after a configurable period (default: 1 hour)
Session data includes authentication state, user info, and available auth methods
After successful authentication, sessions are deleted from Redis

Token-Based Authentication

After successful authentication, the service issues two types of JWTs:

Access Token
- Short-lived token (typically 1 hour)
- Contains user ID, organization ID, user email, and permissions
- Used for authorizing API requests across services
Refresh Token
- Longer-lived token (typically 7 days)
- Used to obtain new access tokens when they expire
- Prevents the need for frequent re-authentication

Both tokens are cryptographically signed with JWT secrets to ensure authenticity.

API Endpoints

Authentication Flow

Core authentication endpoints for initializing and completing the authentication process.

POST /userAccount/initAuth - Initialize Authentication

Start the authentication process for a user.

Request
Response

Endpoint: POST /api/v1/userAccount/initAuthRequest Body Parameters:

Parameter	Type	Required	Description
email	string	Yes	The user’s email address

{
  "email": "user@example.com"
}

Status: 200 OKResponse Headers:

Header	Description
x-session-token	Session token to be used in subsequent authentication requests

{
  "currentStep": 0,
  "allowedMethods": ["password", "otp", "google"],
  "message": "Authentication initialized",
  "authProviders": {
    "google": {
      "clientId": "your-google-client-id.apps.googleusercontent.com"
    }
  }
}

Important Note: The x-session-token is returned in the response headers, not in the response body. This token must be captured and passed in subsequent authenticate requests.

POST /userAccount/authenticate - Authenticate User

Perform authentication with credentials for a specific method.

Request
Response
Error Responses

Endpoint: POST /api/v1/userAccount/authenticateHeaders:

Header	Value	Required	Description
x-session-token	string	Yes	Session token obtained from the initAuth response headers

Request Body Parameters:

Parameter	Type	Required	Description
method	string	Yes	Authentication method (password, otp, google, microsoft, azureAd, oauth). `samlSso` is not handled here; see the note below
credentials	object	Yes	Credentials object for the specified method

SAML uses browser redirects, so it has its own sign-in route, GET /api/v1/saml/signIn. Sending "method": "samlSso" to this endpoint returns 400 with “Single sign-on (SAML) can’t be completed with this request. On the sign-in page, choose your organisation’s single sign-on option. Apps calling the API directly should send the browser to /api/v1/saml/signIn instead.”

Authentication Methods:

Password Authentication

{
  "method": "password",
  "credentials": {
    "password": "your-secure-password"
  }
}

OTP Authentication

{
  "method": "otp",
  "credentials": {
    "otp": "123456"
  }
}

Google Authentication

{
  "method": "google",
  "credentials": "google-id-token-string"
}

Microsoft Authentication

{
  "method": "microsoft",
  "credentials": {
    "accessToken": "microsoft-access-token",
    "idToken": "microsoft-id-token"
  }
}

Azure AD Authentication

{
  "method": "azureAd",
  "credentials": {
    "accessToken": "azure-ad-access-token",
    "idToken": "azure-ad-id-token"
  }
}

OAuth Authentication

{
  "method": "oauth",
  "credentials": {
    "accessToken": "oauth-access-token",
    "idToken": "oauth-id-token"
  }
}

Multi-Step Authentication Response:

{
  "status": "success",
  "nextStep": 1,
  "allowedMethods": ["otp"],
  "authProviders": {}
}

Complete Authentication Response:

{
  "message": "Fully authenticated",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Refusals are worded the same way whether or not the email has an account, and take about as long, so the endpoint can’t be used to find out which emails are real.

Situation	Status	Message
Wrong password, unknown email, no password set, password missing from the request, or a locked account	`400`	”The email or password is incorrect. Check both and try again, or use Forgot password to set a new password.”
Wrong, expired or already-used code, no code requested, unknown email, or a locked account	`401`	”That sign-in code isn’t right. Check the most recent code in your email, or request a new one.”
Method not allowed for the current step	`400`	”That sign-in method isn’t turned on for this step. Go back to the sign-in page and use one of the options it shows, or ask your admin which sign-in methods are enabled.”
`samlSso` sent to this endpoint	`400`	See the note in the Request tab
Step completed with a different account than the step before it	`401`	”This step was completed with a different account than the step before it. Start again from the sign-in page and use the same account for every step.”
No `x-session-token` header	`401`	”Invalid session token”
Sign-in session expired or unknown (a sign-in session expires an hour after it starts or after its last completed step)	`401`	”Invalid session”

After five wrong passwords or codes in a row, the account is locked for 24 hours and the owner is emailed. During the lock, even correct credentials get the same answer as a wrong password or code. An expired code now gets the 401 wrong-code answer above, not 410.

OTP Authentication

One-time password generation and validation.

Generate and send an OTP to the user’s email.

Request
Response

Endpoint: POST /api/v1/userAccount/login/otp/generateRequest Body Parameters:

Parameter	Type	Required	Description
email	string	Yes	The user’s email address (must be valid email format)

Validation:

Email must be in valid email format
Request goes through ValidationMiddleware with email validation

{
  "email": "user@example.com"
}

Status: 200 OKThe body is this plain-text message:

If that email can sign in with a code, one is being sent. It works for 10 minutes. If nothing arrives, check your spam folder or try again later.

The answer is the same 200 and message for every email: an account, an unknown email, a locked account, or an email that couldn’t be sent. A code is created and emailed only when the account exists and isn’t locked, and it is sent in the background, so the answer doesn’t wait for the mail server. A failed send is logged on the server. This endpoint no longer returns 404 or 403.A code is valid for 10 minutes and can be used once.

OAuth Integration

OAuth token exchange and provider integration.

POST /userAccount/oauth/exchange - Exchange OAuth Token

Exchange OAuth authorization code for tokens.

Request
Response

Endpoint: POST /api/v1/userAccount/oauth/exchangeRequest Body Parameters:

Parameter	Type	Required	Description
code	string	Yes	Authorization code from OAuth provider
email	string	Yes	User’s email address
provider	string	Yes	OAuth provider name
redirectUri	string	Yes	Redirect URI used in OAuth flow

{
  "code": "authorization-code-from-provider",
  "email": "user@example.com",
  "provider": "google",
  "redirectUri": "https://your-app.com/callback"
}

Status: 200 OK

{
  "access_token": "oauth-access-token",
  "id_token": "oauth-id-token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Password Management

Password reset, change, and recovery operations.

POST /userAccount/password/forgot - Forgot Password

Initiate password reset process via email.

Request
Response

Endpoint: POST /api/v1/userAccount/password/forgotRequest Body Parameters:

Parameter	Type	Required	Description
email	string	Yes	The user’s email address

{
  "email": "user@example.com"
}

Status: 200 OK

{
  "data": "password reset mail sent"
}

POST /userAccount/password/reset/token - Reset Password with Token

Reset password using token from email.

Request
Response

Endpoint: POST /api/v1/userAccount/password/reset/tokenHeaders:

Header	Value	Required	Description
Authorization	Bearer	Yes	Password reset token from email (uses PASSWORD_RESET scope)

Request Body Parameters:

Parameter	Type	Required	Description
password	string	Yes	New password (must meet complexity requirements)

{
  "password": "new-secure-password"
}

Status: 200 OK

{
  "data": "password reset"
}

POST /userAccount/password/reset - Change Password

Change password for authenticated user.

Request
Response

Endpoint: POST /api/v1/userAccount/password/resetHeaders:

Header	Value	Required	Description
Authorization	Bearer	Yes	Valid access token (requires user authentication)

Request Body Parameters:

Parameter	Type	Required	Description
currentPassword	string	Yes	Current password
newPassword	string	Yes	New password (must meet complexity requirements)

{
  "currentPassword": "current-password",
  "newPassword": "new-secure-password"
}

Status: 200 OK

{
  "data": "password reset"
}

Token Management

Token refresh and session management operations.

POST /userAccount/refresh/token - Refresh Token

Refresh access token using refresh token.

Request
Response

Endpoint: POST /api/v1/userAccount/refresh/tokenHeaders:

Header	Value	Required	Description
Authorization	Bearer	Yes	Valid refresh token (uses TOKEN_REFRESH scope)

Request Body Parameters: No body parameters required.

Status: 200 OK

{
  "user": {
    "_id": "60d21b4667d0d8992e610c85",
    "email": "user@example.com",
    "fullName": "John Doe",
    "orgId": "60a2b5e3a1b3c4d5e6f7g8h9"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

POST /userAccount/logout/manual - Logout

Logout user and invalidate session.

Request
Response

Endpoint: POST /api/v1/userAccount/logout/manualHeaders:

Header	Value	Required	Description
Authorization	Bearer	Yes	Valid access token (requires user authentication)

Request Body Parameters: No body parameters required.

Status: 200 OKNote: This endpoint returns an empty response body (status 200 only).

SAML SSO Integration

SAML Single Sign-On authentication and configuration.

Initiate SAML authentication flow.

Request
Response

Endpoint: GET /api/v1/saml/signInQuery Parameters:

Parameter	Type	Required	Description
email	string	Yes	The user’s email address
sessionToken	string	Yes	Session token from init authentication

GET /api/v1/saml/signIn?email=user@example.com&sessionToken=session-token-123

Handle SAML authentication response from Identity Provider.

Request
Response

Endpoint: POST /api/v1/saml/signIn/callbackThis endpoint is called by the Identity Provider after successful authentication. No manual parameters needed as this is part of the SAML flow.

Status: 200 OKRedirects to /auth/sign-in/samlSso/success with authentication cookies.

POST /saml/updateAppConfig - Update SAML App Config

Update SAML application configuration.

Request
Response

Endpoint: POST /api/v1/saml/updateAppConfigHeaders:

Header	Value	Required	Description
Authorization	Bearer	Yes	Valid scoped token with FETCH_CONFIG scope

Status: 200 OK

{
  "message": "Auth configuration updated successfully",
  "config": {
    // Updated configuration object
  }
}

Organization Auth Configuration

Manage organization-wide authentication settings and methods.

GET /orgAuthConfig/authMethods - Get Auth Methods

Retrieve current authentication methods configuration.

Request
Response

Endpoint: GET /api/v1/orgAuthConfig/authMethodsHeaders:

Header	Value	Required	Description
Authorization	Bearer	Yes	Valid admin access token

Status: 200 OK

{
  "authMethods": [
    {
      "order": 1,
      "allowedMethods": [
        {
          "type": "password"
        },
        {
          "type": "otp"
        }
      ]
    },
    {
      "order": 2,
      "allowedMethods": [
        {
          "type": "google"
        }
      ]
    }
  ]
}

POST /orgAuthConfig/updateAuthMethod - Update Auth Methods

Update organization authentication methods configuration.

Request
Response

Endpoint: POST /api/v1/orgAuthConfig/updateAuthMethodHeaders:

Header	Value	Required	Description
Authorization	Bearer	Yes	Valid admin access token

Request Body Parameters:

Parameter	Type	Required	Description
authMethod	array	Yes	Array of authentication steps

Auth Method Structure:

{
  "authMethod": [
    {
      "order": 1,
      "allowedMethods": [
        {
          "type": "password"
        },
        {
          "type": "otp"
        }
      ]
    },
    {
      "order": 2,
      "allowedMethods": [
        {
          "type": "google"
        }
      ]
    }
  ]
}

Validation Rules:

Must have between 1 and 3 authentication steps
Each step must have a unique order number
At least one authentication method is required per step
No duplicate authentication methods within the same step
No duplicate authentication methods across different steps
Each authentication method can only be used once in the entire configuration
samlSso can only be used in a one-step configuration. A configuration with more than one step that includes samlSso in any step is refused with 400: “SAML single sign-on can’t be combined with other sign-in steps yet. Use SAML on its own as a one-step sign-in, or remove it from the policy.” One step that offers SAML alongside other methods (for example SAML or password) is allowed

Supported Authentication Types:

password - Username/password authentication
otp - One-time password via email
google - Google OAuth authentication
microsoft - Microsoft OAuth authentication
azureAd - Azure Active Directory authentication
oauth - Generic OAuth authentication
samlSso - SAML Single Sign-On

Status: 200 OK

{
  "message": "Auth method updated",
  "authMethod": [
    {
      "order": 1,
      "allowedMethods": [
        {
          "type": "password"
        },
        {
          "type": "google"
        }
      ]
    },
    {
      "order": 2,
      "allowedMethods": [
        {
          "type": "otp"
        }
      ]
    }
  ]
}

POST /orgAuthConfig/ - Setup Org Auth Config

Initialize organization authentication configuration.

Request
Response

Endpoint: POST /api/v1/orgAuthConfig/Headers:

Header	Value	Required	Description
Authorization	Bearer	Yes	Valid admin access token

Request Body Parameters:

Parameter	Type	Required	Description
contactEmail	string	Yes	Organization contact email
registeredName	string	Yes	Organization registered name
adminFullName	string	Yes	Admin’s full name
sendEmail	boolean	No	Whether to send email notifications (default: false)

{
  "contactEmail": "admin@example.com",
  "registeredName": "Example Corporation",
  "adminFullName": "John Admin",
  "sendEmail": false
}

Status: 200 OK

{
  "message": "Org Auth Config created successfully"
}

Internal Endpoints

Internal service-to-service endpoints for configuration and validation.

GET /userAccount/internal/password/check - Check Password Method

Check if password authentication is enabled for the organization.

Request
Response

Endpoint: GET /api/v1/userAccount/internal/password/checkHeaders:

Header	Value	Required	Description
Authorization	Bearer	Yes	Valid scoped token with FETCH_CONFIG scope

Status: 200 OK

{
  "isPasswordAuthEnabled": true
}

Security Considerations

The Authentication Service implements several security measures:

Password Security

Passwords are validated for complexity requirements (minimum 8 characters with at least one uppercase, one lowercase, one number, and one special character)
Passwords are hashed using bcrypt with salt rounds
Forgot-password links work once and expire after 20 minutes. Self-hosted deployments can change that lifetime with the PASSWORD_RESET_LINK_EXPIRY environment variable (for example 30m). Invitation links are separate: a link to set a first password lasts 48 hours and ignores that setting. When password sign-in is turned off, the invitation links to the sign-in page instead, so it doesn’t expire

Brute Force Protection

Failed login attempts are tracked per user account
Accounts are automatically blocked after 5 consecutive failed attempts
Suspicious login attempts trigger notification emails
Blocked accounts require admin intervention to restore access

Session Security

Session tokens are generated as UUIDs
Sessions have limited lifetime (default: 1 hour) and are stored in Redis
Sessions are invalidated after successful authentication or timeout
Session data is encrypted and contains minimal user information

JWT Security

Tokens are signed with secure secrets
Different scopes are used for different token types (auth, refresh, password reset, etc.)
Access tokens have short lifetimes (typically 1 hour)
Refresh tokens have longer lifetimes (typically 7 days)

OAuth Security

OAuth tokens are validated against provider endpoints
Email verification ensures token authenticity
Provider-specific validation for Google, Microsoft, and Azure AD
Generic OAuth support with configurable endpoints

SAML Security

SAML responses are cryptographically verified
Certificate-based validation
Configurable email field mapping
Relay state protection against CSRF attacks

Error Handling

Errors use the API’s standard shape:

{
  "error": {
    "code": "HTTP_BAD_REQUEST",
    "message": "The email or password is incorrect. Check both and try again, or use Forgot password to set a new password.",
    "requestId": "…"
  }
}

requestId is included when the request has one. The codes you’ll see from these endpoints:

HTTP_BAD_REQUEST - A request the service refuses, including a wrong password (see the /authenticate error table)
HTTP_UNAUTHORIZED - A missing, invalid or expired sign-in token or sign-in session; a failed sign-in-code check (wrong, expired or already-used code, no code requested, unknown email, or a locked account); or a sign-in step completed with a different account. A wrong current password on the change-password endpoint is also HTTP_UNAUTHORIZED (“Current password is incorrect.”). On /authenticate, a wrong password is HTTP_BAD_REQUEST instead
HTTP_FORBIDDEN - Not allowed, for example an OAuth token without the required scope
HTTP_NOT_FOUND - Resource not found
VALIDATION_ERROR - The request body or parameters don’t match the expected format
INTERNAL_ERROR - A failure on PipesHub’s side; the message doesn’t describe internals

There is no separate code for a locked account. A locked account gets the same answer as a wrong password (HTTP_BAD_REQUEST) or a wrong sign-in code (HTTP_UNAUTHORIZED), so that sign-in doesn’t reveal whether an account exists.

Important Notes

Session Token Management: The x-session-token header is critical for multi-step authentication flows
Password Complexity: Passwords must meet minimum security requirements
Account Blocking: Users are automatically blocked for 24 hours after 5 failed login attempts, and the owner is emailed. Sign-in answers a blocked account the same way as a wrong password or code
Token Scopes: Different endpoints require different token scopes for access
Multi-Factor Authentication: Organizations can configure multiple authentication steps
Provider Configuration: OAuth and SAML providers require proper configuration
Email Validation: All email fields are validated for proper format
Security Headers: Proper headers must be included for authentication flows

Welcome To PipesHub

System Overview

Authentication

Mail Configuration

Web Search

AI Providers

Connectors

Integrations

Agents

Toolsets

MCP Server

User Management

Deployment

Developer

Additional Resources

Authentication

Authentication Service

Base URL

Authentication

Architecture Overview

Authentication Flow Process

Data Models

Session Management with Redis

Token-Based Authentication

API Endpoints

Security Considerations

Password Security

Brute Force Protection

Session Security

JWT Security

OAuth Security

SAML Security

Error Handling

Important Notes

​Authentication Service

​Base URL

​Authentication

​Architecture Overview

​Authentication Flow Process

​Data Models

​Session Management with Redis

​Token-Based Authentication

​API Endpoints

​Security Considerations

​Password Security

​Brute Force Protection

​Session Security

​JWT Security

​OAuth Security

​SAML Security

​Error Handling

​Important Notes

Authentication Service

Base URL

Authentication

Architecture Overview

Authentication Flow Process

Data Models

Session Management with Redis

Token-Based Authentication

API Endpoints

Security Considerations

Password Security

Brute Force Protection

Session Security

JWT Security

OAuth Security

SAML Security

Error Handling

Important Notes