Architecture & Headless UI

Shyntr is headless by design. We don't force a generic login page on you. This architectural decision gives you complete control over your user experience while Shyntr handles all the complex authentication plumbing.

Headless Philosophy

Traditional identity solutions bundle authentication logic with their own UI components. This creates several problems:

• Limited customization options
• Inconsistent user experience across your application
• Vendor lock-in on visual design
• Difficult integration with existing design systems

Shyntr solves this by completely separating concerns:

┌─────────────────────────────────────────────────────────────┐
│                    Your Application                          │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Login UI   │  │ Consent UI  │  │     Logout UI       │  │
│  │  (React,    │  │  (Your own  │  │  (Custom branded    │  │
│  │  Next.js,   │  │   design)   │  │   experience)       │  │
│  │  Vue, etc.) │  │             │  │                     │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         │                │                     │             │
│         └────────────────┼─────────────────────┘             │
│                          │                                   │
│                   Admin API Calls                            │
└──────────────────────────┼──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                        Shyntr                                │
│  ┌────────────────────────────────────────────────────────┐ │
│  │              Authentication Engine                      │ │
│  │  • Challenge Generation    • Token Issuance            │ │
│  │  • Session Management      • Protocol Translation      │ │
│  │  • Security Validation     • Multi-Tenancy             │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

The Headless Flow

Here's how authentication works with Shyntr's headless architecture:

Step 1: Challenge Generation

When a user needs to authenticate, Shyntr generates a unique login_challenge and redirects the user to your External Login UI.

User → Application → Shyntr → Your Login UI
                              (with login_challenge)

Step 2: User Verification

Your UI takes over. You have complete freedom to implement:

• Username/password authentication
• Multi-factor authentication (MFA)
• Social login buttons
• SAML/OIDC SSO flows
• Biometric authentication
• Magic links
• Any custom authentication method

Example: React Login Component

import { useSearchParams } from 'react-router-dom';

function LoginPage() {
  const [searchParams] = useSearchParams();
  const loginChallenge = searchParams.get('login_challenge');
  
  const handleLogin = async (credentials) => {
    // 1. Validate credentials against your system
    const user = await validateUser(credentials);
    
    // 2. Accept the login challenge with Shyntr
    const response = await fetch('/admin/login/accept', {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        login_challenge: loginChallenge,
        subject: user.id,
        context: {
          email: user.email,
          name: user.name
        }
      })
    });
    
    // 3. Redirect to continue the flow
    const { redirect_to } = await response.json();
    window.location.href = redirect_to;
  };
  
  return (
    <form onSubmit={handleLogin}>
      {/* Your beautiful custom login form */}
    </form>
  );
}

Step 3: Accept the Challenge

Your UI calls Shyntr's Admin API (PUT /admin/login/accept) with:

• The authenticated User ID (subject)
• Context claims (email, name, roles, etc.)
• Optional session parameters

Accept Login Request

curl -X PUT "http://localhost:7497/admin/login/accept" \
  -H "Content-Type: application/json" \
  -d '{
    "login_challenge": "challenge_abc123",
    "subject": "user_12345",
    "remember": true,
    "remember_for": 3600,
    "context": {
      "email": "user@example.com",
      "name": "John Doe"
    }
  }'

Step 4: Token Issuance

Shyntr verifies the handshake, performs security validations, and issues the tokens:

• Access Token: For API authorization
• Refresh Token: For session renewal
• ID Token: For user identity (OIDC)

Token Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "v1.refresh.abc123...",
  "id_token": "eyJhbGciOiJSUzI1NiIs..."
}

Consent Flow

The consent flow follows a similar pattern for OAuth2/OIDC scope approval:

┌──────────────────────────────────────────────────────────────┐
│                     Consent Flow                             │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Shyntr redirects to → EXTERNAL_CONSENT_URL               │
│     (with consent_challenge parameter)                       │
│                                                              │
│  2. Your Consent UI shows:                                   │
│     • Requesting application details                         │
│     • Requested scopes/permissions                           │
│     • User confirmation buttons                              │
│                                                              │
│  3. User grants/denies → Your UI calls:                      │
│     PUT /admin/consent/accept (or /reject)                   │
│                                                              │
│  4. Shyntr issues tokens with approved scopes                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Configuration

Configure your external UI URLs in Shyntr's environment:

.env

# Your Login UI endpoint
EXTERNAL_LOGIN_URL=https://auth.yourapp.com/login

# Your Consent UI endpoint
EXTERNAL_CONSENT_URL=https://auth.yourapp.com/consent

Production Security

In production, always use HTTPS for your external UI URLs. Shyntr will validate redirect URIs strictly to prevent open redirect attacks.

Admin API Endpoints

Endpoint	Method	Description
/admin/login	GET	Get login challenge details
/admin/login/accept	PUT	Accept and complete login
/admin/login/reject	PUT	Reject login attempt
/admin/consent	GET	Get consent challenge details
/admin/consent/accept	PUT	Accept consent request
/admin/consent/reject	PUT	Reject consent request
/admin/logout	GET	Get logout request details
/admin/logout/accept	PUT	Accept logout request

Benefits of Headless Architecture

Aspect	Benefit
Design Freedom	Use any frontend framework—React, Vue, Angular, Next.js, or plain HTML
Brand Consistency	Match your login experience to your product's design language
A/B Testing	Experiment with different login flows without touching auth logic
Accessibility	Implement custom accessibility features for your users
Localization	Full control over language and regional customization
Performance	Optimize your UI independently from the auth backend

Best Practice

Build your Auth Portal (Login, Consent, Logout UIs) as a dedicated micro-frontend. This allows independent deployment and scaling while maintaining a clean separation of concerns.

Next Steps

• Configure Environment Variables for your deployment
• Follow the Headless Login & Consent Guide for implementation details
• Learn about Multi-Tenancy for SaaS deployments