SSO Sign-In/Sign-Up Integration Guide

Create or update users and authenticate in one seamless flow

On this page

Overview

The Nymzie SSO Sign-In/Sign-Up flow allows partners to create new users OR update existing users and authenticate them in a single API call. This eliminates the need to check if a user exists before authentication.

Key Features

  • ✅ Create or Update: Automatically creates new users or updates existing ones based on sso_unique_user_id
  • ✅ Single Flow: One endpoint handles both user management and authentication
  • ✅ Relationship Management: Automatically links parents with children
  • ✅ Immediate Authentication: Users are authenticated right after creation/update
  • ✅ Institution Isolation: Secure multi-tenant architecture

When to Use This Flow

Use Sign-In/Sign-Up flow when:

  • You want to create new users in Nymzie
  • You want to update existing user information
  • You don't have Nymzie user IDs yet
  • You're building a seamless onboarding experience

Use existing flow (with user_id) when:

  • You already have Nymzie user IDs
  • You only need to authenticate existing users
  • No user data updates are needed

Quick Start

Prerequisites

  1. SSO API Credentials from Nymzie administrators
  2. Institution Assignment to your school/organization
  3. Unique User IDs from your system for all users

Basic Integration (3 Steps)

Step 1: Prepare User Data

const userData = {
  user_type: "STUDENT",
  institution_id: 1,
  student: {
    sso_unique_user_id: "YOUR-SYSTEM-USER-123",
    first_name: "John",
    last_name: "Doe",
    grade: "GRADE_10",
    email: "john@student.com"
  }
};

Step 2: Call API

const response = await fetch('https://beta.nymzie.com/api/v1/users/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': 'your-partner-name'
  },
  body: JSON.stringify(userData)
});

Step 3: Redirect User

const { validation_token, frontend_url } = await response.json();
window.location.href = frontend_url; // Automatic login

Authentication

All requests require partner API credentials provided by Nymzie.

Required Headers

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

Environment Configuration

# Beta
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
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

User Types & Flows

The system supports three user types with different relationship structures.

1. EDUCATOR Flow

Use Case: Creating/updating individual educators

Required Fields:

  • user_type: "EDUCATOR"
  • institution_id: Required
  • educator: Object with educator data
  • educator.grades: Array of grades (required)

2. PARENT Flow

Use Case: Creating/updating parents with their children

Required Fields:

  • user_type: "PARENT"
  • parent: Object with parent data
  • parent.phone_number: Required
  • students: Array of at least 1 student (required)

Note: Parent's institution is automatically set based on first child's institution.

3. STUDENT Flow

Use Case: Creating/updating students with their parents

Required Fields:

  • user_type: "STUDENT"
  • institution_id: Required
  • student: Object with student data
  • student.grade: Single grade (required)
  • parents: Array of parents (optional)

Field Specifications

Common Fields (All User Types)

Field Type Required Validation Description
sso_unique_user_id string ✅ Yes Max 255 chars, Unique Your system's unique user ID
first_name string ✅ Yes Max 100 chars User's first name
middle_name string ❌ No Max 100 chars User's middle name
last_name string ✅ Yes Max 100 chars User's last name
email string ❌ No Valid email format User's email address
phone_number string Varies International format User's phone number
gender string ❌ No UPPERCASE MALE, FEMALE, OTHER
dob string ❌ No Date format (YYYY-MM-DD) Date of birth

Available Grades

Grades must use the GradeEnum values (uppercase with underscore):

"GRADE_1", "GRADE_2", "GRADE_3", "GRADE_4", "GRADE_5", "GRADE_6",
"GRADE_7", "GRADE_8", "GRADE_9", "GRADE_10", "GRADE_11", "GRADE_12"

Request Examples

Example 1: EDUCATOR Sign-In/Sign-Up

{
  "user_type": "EDUCATOR",
  "institution_id": 1,
  "expiration_minutes": 15,
  "educator": {
    "sso_unique_user_id": "EDU-12345",
    "first_name": "Sarah",
    "middle_name": "Jane",
    "last_name": "Johnson",
    "email": "sarah.johnson@school.com",
    "phone_number": "+1234567890",
    "gender": "FEMALE",
    "dob": "1985-06-15",
    "grades": ["GRADE_10", "GRADE_11", "GRADE_12"]
  }
}

Example 2: PARENT Sign-In/Sign-Up with Multiple Children

{
  "user_type": "PARENT",
  "expiration_minutes": 15,
  "parent": {
    "sso_unique_user_id": "PAR-67890",
    "first_name": "Michael",
    "middle_name": "Robert",
    "last_name": "Smith",
    "email": "michael.smith@parent.com",
    "phone_number": "+1234567891",
    "gender": "MALE",
    "dob": "1978-03-20"
  },
  "students": [
    {
      "sso_unique_user_id": "STU-11111",
      "first_name": "Emma",
      "middle_name": "Grace",
      "last_name": "Smith",
      "email": "emma.smith@student.com",
      "phone_number": "+1234567892",
      "gender": "FEMALE",
      "dob": "2010-08-12",
      "grade": "GRADE_9",
      "institution_id": 1
    },
    {
      "sso_unique_user_id": "STU-22222",
      "first_name": "Oliver",
      "middle_name": "James",
      "last_name": "Smith",
      "email": "oliver.smith@student.com",
      "gender": "MALE",
      "dob": "2012-05-05",
      "grade": "GRADE_7",
      "institution_id": 1
    }
  ]
}

Example 3: STUDENT Sign-In/Sign-Up with Parents

{
  "user_type": "STUDENT",
  "institution_id": 1,
  "expiration_minutes": 15,
  "student": {
    "sso_unique_user_id": "STU-33333",
    "first_name": "Sophia",
    "middle_name": "Marie",
    "last_name": "Williams",
    "email": "sophia.williams@student.com",
    "phone_number": "+1234567893",
    "gender": "FEMALE",
    "dob": "2009-11-22",
    "grade": "GRADE_11"
  },
  "parents": [
    {
      "sso_unique_user_id": "PAR-44444",
      "first_name": "Jennifer",
      "middle_name": "Ann",
      "last_name": "Williams",
      "email": "jennifer.williams@parent.com",
      "phone_number": "+1234567894",
      "gender": "FEMALE",
      "dob": "1980-04-10"
    }
  ]
}

Response Format

Success Response (200 OK)

{
  "api_status": "success",
  "api_message": "SSO sign-in/sign-up completed successfully. User created/updated and session established.",
  "api_data": {
    "session_key": "sso_key_abc123def456",
    "validation_token": "abc123def456ghi789jkl012mno345pq",
    "expires_at": "2025-10-22T15:30:00.000000Z",
    "expires_in": 900,
    "user": {
      "id": 123,
      "type": "STUDENT",
      "sso_unique_user_id": "STU-33333",
      "first_name": "Sophia",
      "last_name": "Williams",
      "email": "sophia.williams@student.com",
      "username": "sophia.williams.1234567893"
    },
    "frontend_url": "https://beta.nymzie.com?session=abc123def456ghi789jkl012mno345pq"
  }
}

What Happens After Response

  1. User is created or updated in Nymzie database
  2. Relationships (parent-child) are established automatically
  3. SSO session is created with validation token
  4. Redirect user to frontend_url → Automatic login → Redirect to dashboard

Error Handling

Common Error Codes

HTTP Status Error Code Description Solution
401 AUTHENTICATION_FAILED Invalid API credentials Verify API key and secret
403 INSTITUTION_ACCESS_DENIED Institution mismatch Ensure user belongs to your institution
404 PARTNER_NOT_FOUND Partner not found or inactive Contact Nymzie support
422 VALIDATION_ERROR Invalid request data Check required fields and formats
500 SSO_SIGNIN_SIGNUP_FAILED Server error Retry or contact support

Testing

Test Scenarios

  1. ✅ Create new educator via SSO
  2. ✅ Update existing educator (change name, grades)
  3. ✅ Create new parent + 2 students via SSO
  4. ✅ Update existing parent, add new student
  5. ✅ Create new student + 2 parents via SSO
  6. ✅ Link existing student to new parent
  7. ✅ Test validation errors (missing required fields)
  8. ✅ Test institution isolation (cannot access other institutions)

Postman Collection

Access the complete Postman collection with test cases:

https://documenter.getpostman.com/view/34556976/2sB3BGJACV

Best Practices

1. SSO Unique User ID Management

✅ DO:

  • Use your system's unique, stable user IDs
  • Keep the format consistent (e.g., "EDU-{id}", "STU-{id}", "PAR-{id}")
  • Store the mapping between your ID and Nymzie user ID
  • Use unique IDs that won't change over time

❌ DON'T:

  • Use email addresses as sso_unique_user_id (emails can change)
  • Use sequential numbers without prefixes (hard to debug)
  • Reuse sso_unique_user_id for different users

2. Security

✅ DO:

  • Store API credentials in environment variables
  • Use HTTPS for all API calls
  • Implement proper error handling
  • Log all SSO attempts for audit purposes
  • Rotate credentials periodically

❌ DON'T:

  • Expose API credentials in client-side code
  • Store credentials in version control
  • Share credentials between environments (beta/production)

Support & Resources

Document Version: 1.0.0
Last Updated: October 22, 2025
API Version: v1
© 2025 Nymzie Learning Platform. All rights reserved.