SSO Partner Integration Guide

🎯 Integration Options

Nymzie offers two SSO integration flows to suit different use cases:

1. Sign-In/Sign-Up Flow (Recommended for New Integrations)

Best for: Creating new users OR updating existing users and authenticating in one call

✅ Use when:

Building a new integration from scratch
You want to create users on-the-fly during authentication
You need to sync user data with Nymzie during login
You don't have Nymzie user IDs yet

📚 View Complete Sign-In/Sign-Up Guide →

Example:

{
  "user_type": "STUDENT",
  "institution_id": 1,
  "student": {
    "sso_unique_user_id": "YOUR-SYSTEM-USER-123",
    "first_name": "John",
    "last_name": "Doe",
    "grade": "GRADE_10"
  }
}

2. Existing User Flow (This Document)

Best for: Authenticating existing Nymzie users by their user ID

✅ Use when:

Users already exist in Nymzie
You have Nymzie user IDs stored in your system
You only need authentication without user management
You're maintaining an existing integration

Example:

{
  "user_id": 23,
  "user_type": "STUDENT",
  "expiration_minutes": 15
}

Quick Comparison

Feature	Sign-In/Sign-Up Flow	Existing User Flow
Creates new users	✅ Yes	❌ No
Updates user data	✅ Yes	❌ No
Requires Nymzie user_id	❌ No	✅ Yes
Requires sso_unique_user_id	✅ Yes	❌ No
Manages relationships	✅ Yes (parent-child)	❌ No
User discovery needed	❌ No	✅ Yes
Best for	New integrations	Existing integrations

🚀 Core Integration Flow (Existing Users)

The Nymzie SSO integration follows a simple 3-step process that allows partner applications to seamlessly authenticate users into the Nymzie learning platform.

🎯 Key Integration Points

Session Creation: Your app creates a temporary SSO session
User Redirect: User is redirected to Nymzie with the validation token
Auto-Authentication: Nymzie validates the token and logs in the user

🏫 School-Specific Integration Examples

Each partner is associated with a specific school/institution for secure isolation. Here are examples of how this works:

Example Partner Configurations:

BrainHill International School → Partner: "BrainHill Smart App"
Zoe International Academy → Partner: "Zoe International Smart App"
Emily Bennett International School → Partner: "Emily Bennett Smart App"

Note: These are examples for illustration. Your actual school name and partner identifier will be different and will be provided by Nymzie administrators.

✅ Supported User Types

Type	Description	Use Case
`STUDENT`	Student users	Access educational materials, practice questions, assessments, and past questions
`EDUCATOR`	Teacher/instructor users	Create practice questions, manage content, and moderate discussions
`PARENT`	Parent users	Monitor child's learning progress, view reports and activities

Note: Only STUDENT, EDUCATOR, and PARENT user types are supported for partner SSO integration.

🚀 Quick Start

Step 1: Get Your Credentials

Contact Nymzie administrators to receive your school-specific SSO credentials:

{
  "partner_name": "brainhill-smartapp",
  "api_key": "nymzie_rqUsh5Umyj4IFRn5hhcss7cDsIar9VZd",
  "api_secret": "Vexn8nbdzooyCQhNw7UgkiAYmXVBf3yNJq3FrNZTg7n3zkQogow8WrACvypehf8t",
  "institution": "BrainHill International School",
  "institution_id": 1
}

Step 2: Set Up Environment

Store your credentials securely:

# Beta Environment
NYIMZIE_API_KEY=your_beta_api_key
NYIMZIE_API_SECRET=your_beta_api_secret
NYIMZIE_SSO_URL=https://beta.nymzie.com/api/v1/users
NYIMZIE_FRONTEND_URL=https://beta.nymzie.com

# Production Environment
NYIMZIE_API_KEY=your_production_api_key
NYIMZIE_API_SECRET=your_production_api_secret
NYIMZIE_SSO_URL=https://nymzie.com/api/v1/users
NYIMZIE_FRONTEND_URL=https://nymzie.com

Step 3: Basic Integration

// Create SSO session
const session = await fetch('/sso/sessions/initiate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.NYIMZIE_API_KEY,
    'X-API-Secret': process.env.NYIMZIE_API_SECRET,
    'X-Source-App': 'brainhill-smartapp'
  },
  body: JSON.stringify({
    user_id: 23,
    user_type: 'STUDENT'
  })
});

// Redirect user to Nymzie
const { validation_token, frontend_url } = await session.json();
window.location.href = frontend_url;

Step 4: Test Integration

Use the provided Postman collection to test all endpoints before going live.

📡 API Endpoints

Base URL

Production: https://nymzie.com/api/v1/users
Beta: https://beta.nymzie.com/api/v1/users

Frontend URLs:

Production: https://nymzie.com
Beta: https://beta.nymzie.com

Note: All examples in this document use beta URLs. For production, replace beta.nymzie.com with nymzie.com.

1. Create SSO Session

Endpoint: POST /sso/sessions/initiate

Purpose: Create a new SSO session for a user

Headers:

Content-Type: application/json
Accept: application/json
X-API-Key: {your_api_key}
X-API-Secret: {your_api_secret}
X-Source-App: {your_app_name}

Request Body:

{
  "user_id": 23,
  "user_type": "STUDENT",
  "expiration_minutes": 15,
  "metadata": {
    "institution_id": 1
  }
}

Parameters:

Field	Type	Required	Description
`user_id`	integer	✅	Valid Nymzie user ID
`user_type`	string	✅	Must match user's actual type
`expiration_minutes`	integer	❌	Session duration (1-120, default: 15)
`metadata`	object	❌	Additional session data (optional)
`metadata.institution_id`	integer	❌	Institution context (optional)

Success Response (200):

{
  "api_status": "success",
  "api_message": "SSO session created successfully.",
  "api_data": {
    "validation_token": "abc123def456ghi789jkl012mno345pq",
    "expires_at": "2025-08-12T14:07:30.000000Z",
    "expires_in": 900,
    "user": {
      "id": 23,
      "type": "STUDENT",
      "first_name": "Rexford",
      "last_name": "Boakye",
      "email": "rexboa@gmail.com"
    },
    "frontend_url": "https://beta.nymzie.com?session=abc123def456ghi789jkl012mno345pq"
  }
}

Error Responses:

// 401 - Authentication Failed
{
  "api_status": "error",
  "api_message": "Authentication failed. Invalid API credentials.",
  "api_data": {
    "error_code": "AUTHENTICATION_FAILED"
  }
}

// 422 - User Type Mismatch
{
  "api_status": "error",
  "api_message": "User type mismatch. The provided user type does not match the user's actual type.",
  "api_data": {
    "error_code": "USER_TYPE_MISMATCH"
  }
}

// 422 - User Not Approved
{
  "api_status": "error",
  "api_message": "User account is not active or approved.",
  "api_data": {
    "error_code": "USER_NOT_APPROVED"
  }
}

// 403 - Institution Access Denied
{
  "api_status": "error",
  "api_message": "User does not belong to the partner's institution.",
  "api_data": {
    "error_code": "INSTITUTION_ACCESS_DENIED"
  }
}

🔍 Validation & Security

Automatic Validation Checks:

✅ API Credentials: Validates your API key, secret, and source app
✅ Partner Status: Ensures your partner account is active
✅ User Existence: Verifies the requested user exists in Nymzie
✅ Institution Access: Automatically blocks cross-institution access
✅ User Type Match: Ensures user type matches the actual user
✅ User Status: Confirms user account is active and approved

Institution Security Example:

// ❌ This will FAIL if user 45 belongs to a different institution
const response = await fetch('/sso/sessions/initiate', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_key',
    'X-API-Secret': 'your_secret',
    'X-Source-App': 'brainhill-smartapp'
  },
  body: JSON.stringify({
    user_id: 45,  // User from different school
    user_type: 'STUDENT'
  })
});

// Response: 403 - Institution Access Denied
// "User does not belong to the partner's institution."

🌐 Frontend Integration

Secure Validation Token Flow

Redirect users to Nymzie using the secure validation token:

// Example: JavaScript redirect with validation token
function redirectToNymzie(validationToken) {
  const url = `https://beta.nymzie.com?session=${validationToken}`;

  // For security, open in the same window
  window.location.href = url;
}

// Usage
redirectToNymzie('abc123def456ghi789...');

Note: For security reasons, API credentials are no longer passed in the redirect URL. All users are automatically redirected to the dashboard after successful SSO authentication.

Complete Integration Example

class NymzieSSOClient {
  constructor(apiKey, apiSecret, sourceApp, baseUrl) {
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
    this.sourceApp = sourceApp;
    this.baseUrl = baseUrl;
  }

  async createSession(userId, userType, options = {}) {
    const response = await fetch(`${this.baseUrl}/sso/sessions/initiate`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'X-API-Key': this.apiKey,
        'X-API-Secret': this.apiSecret,
        'X-Source-App': this.sourceApp
      },
      body: JSON.stringify({
        user_id: userId,
        user_type: userType,
        expiration_minutes: options.expirationMinutes || 15,
        metadata: options.metadata || {}
      })
    });

    const data = await response.json();

    if (data.api_status !== 'success') {
      throw new Error(data.api_message || 'SSO session creation failed');
    }

    return data.api_data;
  }

  redirectUser(validationToken) {
    // Secure redirect using validation token only
    window.location.href = `https://beta.nymzie.com?session=${validationToken}`;
  }

  async authenticateUser(userId, userType) {
    try {
      const sessionData = await this.createSession(userId, userType);

      // Redirect user using validation token (automatic dashboard redirect)
      this.redirectUser(sessionData.validation_token);
    } catch (error) {
      console.error('SSO Authentication failed:', error);
      throw error;
    }
  }
}

// Usage Example for BrainHill International School
const ssoClient = new NymzieSSOClient(
  process.env.NYIMZIE_API_KEY,
  process.env.NYIMZIE_API_SECRET,
  'brainhill-smartapp',
  'https://beta.nymzie.com/api/v1/users'
);

// Authenticate a student (automatic dashboard redirect)
await ssoClient.authenticateUser(23, 'STUDENT');

❌ Error Handling

Common Error Codes

Code	HTTP Status	Description	Solution
`AUTHENTICATION_FAILED`	401	Invalid API credentials	Verify API key and secret
`PARTNER_NOT_FOUND`	401	Partner not found or inactive	Contact Nymzie support
`USER_NOT_FOUND`	404	User ID doesn't exist	Verify user ID in Nymzie
`INSTITUTION_ACCESS_DENIED`	403	User belongs to different institution	Verify user belongs to your school
`USER_TYPE_MISMATCH`	422	User type doesn't match	Check user's actual type
`USER_NOT_APPROVED`	422	User account not active	User needs approval
`RATE_LIMIT_EXCEEDED`	429	Too many requests	Implement backoff strategy

Error Response Format

{
  "api_status": "error",
  "api_message": "Human-readable error description",
  "api_data": {
    "error_code": "MACHINE_READABLE_CODE",
    "details": "Additional error context (optional)"
  }
}

🧪 Testing

Postman Collection

Postman Documentation Link:
https://documenter.getpostman.com/view/34556976/2sB3BGJACV

The collection includes:

✅ Admin endpoints for credential management
✅ Partner endpoints for SSO session creation
✅ Frontend tests for complete flow validation
✅ Error scenarios for failure testing
✅ Automated test scripts for response validation

Test Scenarios

1. Successful SSO Flow

# 1. Create session for BrainHill International School
curl -X POST https://beta.nymzie.com/api/v1/users/sso/sessions/initiate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "X-Source-App: brainhill-smartapp" \
  -d '{"user_id": 23, "user_type": "STUDENT"}'

# 2. Test frontend URL from response
# Open the frontend_url in a browser

2. Authentication Failure Test

# Test with invalid credentials
curl -X POST https://beta.nymzie.com/api/v1/users/sso/sessions/initiate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: invalid_key" \
  -H "X-API-Secret: invalid_secret" \
  -H "X-Source-App: brainhill-smartapp" \
  -d '{"user_id": 23, "user_type": "STUDENT"}'

📞 Support

Technical Support

Email: support@npontu.com
Postman Collection: Included with this guide