Auth Usage and Scenarios

This document explains how to use Fabrixly-IDS for all common authentication patterns: interactive UI-to-API login, machine-to-machine (M2M) service authentication, and the supported user authentication modes.

It is written so that a developer or product manager can read it and understand exactly which flow to choose, when to use it, and what tokens or session behavior to expect.

1. Overview

Fabrixly-IDS supports two broad classes of authentication:

• Interactive user authentication: a person uses a UI to log in, and the client application receives tokens to call APIs.
• Machine-to-machine authentication: a backend service authenticates directly to Fabrixly-IDS without a user, obtains an access token, and uses it for API-to-API calls.

The platform also supports multiple user authentication modes inside the interactive flow:

• Password-only
• OTP-only (passwordless)
• Password + OTP (2FA)
• Flexible (password or OTP)
• Magic link (schema support exists and can be enabled as needed)

2. Core concepts

Tokens and session behavior

Fabrixly-IDS is an OpenID Connect provider. The service issues several token types:

• ID Token: identifies the authenticated user. Used by the client to confirm the end user and their profile claims.
• Access Token: authorizes API calls. The client sends it to protected backend APIs.
• Refresh Token: optionally issued for long-lived sessions and is used to obtain new access tokens without forcing the user to log in again.

Important endpoints

• /.well-known/openid-configuration — discovery document describing the issuer, authorization endpoint, token endpoint, JWKS URI, supported scopes, and supported response types.
• /auth — interactive authorization endpoint for UI login flows.
• /token — endpoint used by clients to exchange authorization codes, client credentials, or refresh tokens.
• /userinfo — endpoint used to get user claims after login.

3. Interactive UI-to-API scenarios

Interactive login is the most common way to authenticate humans. In Fabrixly-IDS this is typically done with the Authorization Code flow.

3.1 Authorization Code flow (recommended for web apps)

When to use

• Browser-based applications with a backend server.
• Mobile or native apps that support PKCE or can protect a client secret.
• Applications that require user identity plus API access.

How it works

1. The application redirects the browser to Fabrixly-IDS /auth.
2. The user authenticates using the configured auth mode.
3. Fabrixly-IDS redirects back to the app with an authorization code.
4. The backend exchanges the code at /token.
5. The app receives tokens and uses the access token for API calls.

Authorization request example

GET /auth?response_type=code&client_id=web-portal&redirect_uri=https%3A%2F%2Fapp.local%2Fcallback&scope=openid%20profile%20email&state=abc123 HTTP/1.1
Host: ids.fabrixly.com

Authorization response example

HTTP/1.1 302 Found
Location: https://app.local/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=abc123

Token exchange example

POST /token HTTP/1.1
Host: ids.fabrixly.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fapp.local%2Fcallback&client_id=web-portal&client_secret=secret123

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "def50200b1...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}

Call protected API example

GET /api/user/profile HTTP/1.1
Host: api.app.local
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

What you get

• id_token for user identity.
• access_token for API authorization.
• refresh_token for session renewal when configured.

Typical client configuration

• grant_types: authorization_code, refresh_token
• response_types: code
• token_endpoint_auth_method: client_secret_basic or client_secret_post
• redirect_uris: application callback URLs

How to use

• Use Authorization Code for all modern web apps.
• Prefer PKCE for SPAs and native apps.
• Keep the client secret on a trusted backend.
• Always validate state to protect against CSRF.

3.2 Hybrid flow (less common, for legacy or mixed UI requirements)

When to use

• Applications that need immediate identity on the browser and a server-side token exchange.
• Legacy apps where a front-channel id_token is required for UI state.

How it works

1. The app requests response_type=code id_token at /auth.
2. Fabrixly-IDS returns an immediate id_token and an authorization code.
3. The backend exchanges the code at /token for access tokens.

Authorization request example

GET /auth?response_type=code%20id_token&client_id=mixed-app&redirect_uri=https%3A%2F%2Fapp.local%2Fcallback&scope=openid%20profile&nonce=xyz123&state=abc123 HTTP/1.1
Host: ids.fabrixly.com

Authorization response example

HTTP/1.1 302 Found
Location: https://app.local/callback?code=SplxlOBeZQQYbYS6WxSbIA&id_token=eyJhbGciOiJSUzI1NiIs...&state=abc123&scope=openid%20profile

Token exchange example

POST /token HTTP/1.1
Host: ids.fabrixly.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fapp.local%2Fcallback&client_id=mixed-app&client_secret=secret123

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "def50200b1...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile"
}

Typical client configuration

• grant_types: authorization_code, implicit
• response_types: code, id_token

How to use

• Use only for legacy scenarios or when the UI needs immediate identity info.
• Avoid hybrid for new applications if Authorization Code alone is sufficient.

3.3 Implicit flow (rare, browser-only, legacy)

When to use

• Legacy browser apps that cannot perform a secure backend token exchange.
• Clients that cannot keep a secret and require direct browser token delivery.

How it works

1. The browser requests /auth with response_type=id_token token.
2. Fabrixly-IDS returns tokens directly in the browser URL fragment.

Authorization request example

GET /auth?response_type=id_token%20token&client_id=legacy-spa&redirect_uri=https%3A%2F%2Fapp.local%2Fcallback&scope=openid%20profile&nonce=xyz123&state=abc123 HTTP/1.1
Host: ids.fabrixly.com

Authorization response example

HTTP/1.1 302 Found
Location: https://app.local/callback#id_token=eyJhbGciOiJSUzI1NiIs...&access_token=eyJhbGciOiJIUzI1NiIs...&token_type=Bearer&expires_in=3600&state=abc123

What you get

• id_token and access_token directly in the browser.
• No refresh token by default.

Typical client configuration

• grant_types: implicit
• response_types: id_token, token

How to use

• Reserve for legacy SPAs only.
• Use the Authorization Code flow instead when possible.
• Protect against token leakage in browser history and referrers.

3.4 Refresh tokens for session continuity

When to use

• Web or mobile apps that need long-lived sessions.
• Applications that want to avoid repeated logins.

How it works

1. The authorization code exchange returns a refresh_token.
2. When the access token expires, the client calls /token with grant_type=refresh_token.
3. Fabrixly-IDS returns a new access token and optionally rotates the refresh token.

Token refresh request example

POST /token HTTP/1.1
Host: ids.fabrixly.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=def50200b1...&client_id=web-portal&client_secret=secret123

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "def50200b1-new...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}

What you get

• Renewed access tokens without forcing the user to log in again.
• Optionally rotated refresh tokens for stronger security.

How to use

• Store refresh_token securely on the backend or in a safe mobile storage area.
• Use refresh requests only from trusted clients.
• Do not expose refresh tokens in browser fragments.

3.5 Accessing protected APIs

How to use

• Add the access token to API requests using Authorization: Bearer <access_token>.
• Validate the token on every request.
• Check scope and user claims for authorization decisions.

Protected API request example

GET /api/user/profile HTTP/1.1
Host: api.app.local
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Protected API response example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "user_id": "user-123",
  "email": "user@example.com",
  "roles": ["user", "admin"]
}

4. User authentication modes explained

The user-facing login behavior in Fabrixly-IDS is independent of the OAuth/OIDC flow. The login page adapts to the client’s configured auth_mode.

4.1 Password-only

Use when

• Your users already have passwords.
• You need a familiar login experience for internal applications.
• You do not want to use OTP delivery channels.

User sees

• Email or mobile field.
• Password field.
• A single submit button.

Result

• The server validates the password and continues the authorization flow.
• No OTP is generated.

4.2 OTP-only (passwordless)

Use when

• You want to remove passwords and improve user conversion.
• Your users are mobile-first or email-focused.
• You want a modern passwordless experience.

User sees

• Email or mobile field.
• No password field (or password field is disabled).
• A button like “Send OTP.”

Result

• Fabrixly-IDS sends a one-time code by email or SMS.
• The user enters the OTP and is logged in.

4.3 Password + OTP (2FA)

Use when

• You need strong authentication for sensitive applications.
• You want to enforce MFA for compliance.

User sees

• Email/mobile field.
• Password field.
• After password validation, a second OTP prompt.

Result

• Password is validated first.
• A one-time code is sent via email or SMS.
• User enters the OTP to complete login.

4.4 Flexible mode

Use when

• You need to support both password users and passwordless users on the same client.
• Your user audience is mixed.

User sees

• Email/mobile field.
• Password field, but leaving it empty triggers OTP login.
• Optionally, immediate password login.

Result

• If the user provides a password, the session continues immediately.
• If the password is blank, Fabrixly-IDS sends OTP and completes login after verification.

4.5 Magic link

Use when

• You want a true passwordless link-based login.
• Your app can support email magic link delivery.

What to know

• Fabrixly-IDS schema supports magic-link in the client auth mode settings.
• The UI and backend may need additional configuration to render and validate magic links.

4.6 Choosing an auth mode by client type

4.7 Forgot password / reset flow

When to use

• Users forget their password and need a recovery path.
• You want a secure way to reset passwords without exposing account existence.

How it works

1. The user submits their email or phone to /api/auth/forgot-password.
2. Fabrixly-IDS creates a reset token and sends a password reset link by email or SMS.
3. The user clicks the reset link and sets a new password.
4. The user can then log in with the new password.

API request example

POST /api/auth/forgot-password HTTP/1.1
Host: ids.fabrixly.com
Content-Type: application/json

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

API response example

{
  "message": "If an account exists with this email, you will receive a password reset link."
}

Reset password request example

POST /api/auth/reset-password HTTP/1.1
Host: ids.fabrixly.com
Content-Type: application/json

{
  "token": "123e4567-e89b-12d3-a456-426614174000",
  "password": "NewSecurePassw0rd!"
}

Reset password response example

{
  "message": "Password reset successful. You can now log in."
}

How to use

• Use this flow when a user reports a forgotten password.
• Do not reveal whether the email is registered.
• Send the token link via email/SMS with an expiration window.
• After reset, require the user to log in normally.

5. Machine-to-machine (M2M) service authentication

M2M authentication is used when no human user is involved and services need to authenticate directly.

5.1 Client Credentials flow

When to use

• Backend service-to-backend service calls.
• API clients that must access protected resources without a user context.
• Administrative automation or scheduled jobs.

How it works

1. The service sends client credentials to /token.
2. The service receives an access token.
3. The service uses that access token to call APIs.

What you get

• access_token only.
• No id_token because there is no end user.
• No user session.

Typical client configuration

• grant_types: client_credentials
• response_types: []
• token_endpoint_auth_method: client_secret_post or client_secret_basic

How to use

• Use client credentials for backend services, cron jobs, or infrastructure automation.
• Store client_secret securely on the server side.
• Request only the scopes needed by the service.
• Treat the returned access_token as the service identity and validate it on the resource server.

API sequence

• Service -> Fabrixly-IDS /token with grant_type=client_credentials, client_id, client_secret, and optional scope
• Fabrixly-IDS -> JSON response with access_token, token_type, expires_in, and scope

Token request example

POST /token HTTP/1.1
Host: ids.fabrixly.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=service-client&client_secret=secret456&scope=api.read%20api.write

Token response example

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.read api.write"
}

Protected API request example

GET /api/service/data HTTP/1.1
Host: api.service.local
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Example

• client-app-2 is seeded as a pure client credentials client.
• client-scenario-4 is a test client for machine-to-machine scenarios.

5.2 When not to use client credentials

• Do not use it for user login flows.
• Do not use it when the API should act on behalf of an actual user.
• Use Authorization Code instead when user identity is needed.

6. Which flow to choose

7. Practical examples

Example A: Web portal with SSO and API access

• Register a client with grant_types: ["authorization_code", "refresh_token"]
• Use response_types: ["code"]
• Use token_endpoint_auth_method: "client_secret_basic" or client_secret_post
• Use redirect_uris matching the application callback
• Set auth_mode to:
  • password for internal enterprise portals
  • password_and_otp for high-security portals
  • flexible for mixed audiences

Flow:

1. User clicks login button.
2. Browser redirects to Fabrixly-IDS /auth.
3. User authenticates and is redirected back with a code.
4. Backend exchanges code for tokens at /token.
5. Backend stores session and uses access_token for API calls.
6. Use refresh_token to renew session silently.

Example B: Mobile app (interactive login)

• Register a mobile client with grant_types: ["authorization_code"]
• Use response_types: ["code"]
• Prefer PKCE if available
• Use auth_mode: "otp" or flexible for better mobile UX

Flow:

1. App opens browser or webview to Fabrixly-IDS.
2. User logs in by email/OTP or password.
3. App receives authorization code.
4. App exchanges code at /token.
5. App receives tokens and calls backend APIs.

Example C: Service-to-service API access

• Register a backend service client with grant_types: ["client_credentials"]
• Use response_types: []
• Set token_endpoint_auth_method to client_secret_post or client_secret_basic
• No UI is involved

Flow:

1. Service posts client credentials to /token.
2. Fabrixly-IDS returns access_token.
3. Service uses the token to call protected APIs.

Example C.1: Request / response example for service token request

POST /token HTTP/1.1
Host: ids.fabrixly.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=service-client&client_secret=secret456&scope=api.read

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.read"
}

Example D: Testing and demo clients

• client-scenario-1: Authorization code + refresh token
• client-scenario-2: Hybrid mode
• client-scenario-3: Implicit mode
• client-scenario-4: Client credentials mode

8. Quick reference table

9. Practical guidance for implementation

• Always keep redirect_uris exact and secure.
• Do not use implicit if you can use authorization code.
• Use client_credentials only for non-user services.
• If you need user identity, always use an OIDC-enabled flow (authorization code, hybrid, or implicit with id_token).
• If you want the best security for a SPA or mobile app, prefer authorization code and PKCE over implicit.
• Use token_endpoint_auth_method matching the client type and secret handling capability.
• Configure OTP delivery before using otp or password_and_otp.
• For UIs that need mobile login, enable enable_mobile_login and set otp_delivery_method to sms or both.

10. Summary

• UI login flows are for users and produce id_token + access_token.
• M2M flows are for services and produce access_token.
• Choose password for familiar login, otp for passwordless, password_and_otp for MFA, and flexible for mixed users.
• Choose authorization_code for modern apps, client_credentials for services, and only use hybrid/implicit for legacy cases.