Authentication API

The Authentication API provides methods for organization access, user management, and board session validation.

Organization Authentication

Generate Token

Generates a new JWT token for the authenticated organization. This token is used to access board resources.

URL: /auth/token
Method: POST
Headers:
- X-API-Key: Organization API key (Required)

Response

json

{
  "token": "jwt-token-here",
  "expiresIn": "24h",
  "organizationId": "org-uuid"
}

Validate API Key

Validates the provided API key and returns organization information.

URL: /auth/validate
Method: POST
Body:

json

{
  "apiKey": "wb_api_key_here"
}

Response

json

{
  "valid": true,
  "organizationId": "org-uuid"
}

Board Authentication

Validate Board Token

Validates the provided board access token and returns token details including permissions.

URL: /auth/validate-board-token
Method: POST
Body:

json

{
  "token": "board-jwt-token-here"
}

Response

json

{
  "valid": true,
  "boardUuid": "board-uuid",
  "organizationId": "org-uuid",
  "role": "host",
  "permissions": ["read", "write", "admin"],
  "expiresAt": "2025-11-17T10:00:00.000Z"
}

User Authentication

Register

Registers a new user account.

URL: /auth/register
Method: POST
Body:

json

{
  "email": "user@example.com",
  "password": "SecurePassword123",
  "name": "John Doe",
  "organizationName": "My Educational Organization" // Optional
}

Response (201 Created)

json

{
  "id": "user-uuid",
  "email": "user@example.com",
  "created_at": "2025-11-17T10:00:00.000Z"
}

Authenticates a user and returns a JWT token.

URL: /auth/login
Method: POST
Body:

json

{
  "email": "user@example.com",
  "password": "SecurePassword123"
}

Response

json

{
  "access_token": "jwt-token-here",
  "refresh_token": "refresh-token-here",
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "created_at": "2025-11-17T10:00:00.000Z"
  }
}

Logout

Logs out the currently authenticated user.

URL: /auth/logout
Method: POST
Headers:
- Authorization: Bearer <jwt-token>

Response

json

{
  "message": "Logged out successfully"
}

Password Reset

Request Reset

Initiates a password reset process.

URL: /auth/forgot-password
Method: POST
Body:

json

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

Reset Password

Resets a user's password using a reset token.

URL: /auth/reset-password/:token
Method: POST
Body:

json

{
  "password": "NewSecurePassword123"
}

Email Verification

Resend Verification

Resends the email verification.

URL: /auth/resend-verification
Method: POST
Body:

json

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

Verify Email

Verifies a user's email using a verification token.

URL: /auth/verify-email/:token
Method: GET

External System Integration

Verify Student Token (BigBen CRM)

Verifies a student JWT token from BigBen CRM external authentication system. This endpoint enables seamless single sign-on (SSO) integration with legacy CRM systems.

Authentication: None (public endpoint)

Endpoint

http

POST /auth/verify-student-token
Content-Type: application/json

Request Body

Parameter	Type	Required	Description
`user_token`	string	Yes	JWT token from BigBen CRM student authentication

Example:

json

{
  "user_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHVkZW50X2lkIjoiMTIzNDUiLCJleHAiOjE3MzIwMTIzNDV9..."
}

Response

Status Code: 200 OK

json

{
  "valid": true,
  "student_id": "12345",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "expires_at": "2025-11-19T10:00:00.000Z"
}

Response Fields

Field	Type	Description
`valid`	boolean	Token validity status
`student_id`	string	Student ID from BigBen CRM
`name`	string	Student full name
`email`	string	Student email address
`expires_at`	string	ISO 8601 token expiration timestamp

Example Requests

JavaScript/TypeScript:

javascript

// Verify BigBen CRM student token (e.g., from iframe postMessage)
async function verifyStudentToken(userToken) {
  const response = await fetch('https://api.boardapi.io/api/v1/auth/verify-student-token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      user_token: userToken
    })
  });

  const result = await response.json();

  if (result.valid) {
    console.log(`Student verified: ${result.name} (ID: ${result.student_id})`);
    return result;
  } else {
    throw new Error('Invalid student token');
  }
}

// Usage in iframe integration
window.addEventListener('message', async (event) => {
  if (event.data.type === 'BIGBEN_AUTH') {
    try {
      const student = await verifyStudentToken(event.data.token);
      // Grant access to board
      loadBoard(student);
    } catch (error) {
      console.error('Student verification failed:', error);
      showLoginForm();
    }
  }
});

cURL:

bash

curl -X POST https://api.boardapi.io/api/v1/auth/verify-student-token \
  -H "Content-Type: application/json" \
  -d '{
    "user_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

PHP (BigBen CRM integration):

php

<?php
// BigBen CRM integration example
function verifyStudentToken($userToken) {
    $ch = curl_init('https://api.boardapi.io/api/v1/auth/verify-student-token');

    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode(['user_token' => $userToken]),
        CURLOPT_RETURNTRANSFER => true
    ]);

    $response = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if ($response['valid']) {
        return [
            'student_id' => $response['student_id'],
            'name' => $response['name'],
            'email' => $response['email']
        ];
    }

    throw new Exception('Invalid student token');
}

// Usage in BigBen CRM lesson page
$studentToken = $_SESSION['student_jwt_token'];
try {
    $student = verifyStudentToken($studentToken);
    echo "Welcome, {$student['name']}!";
} catch (Exception $e) {
    header('Location: /login');
    exit;
}

Use Cases

Single Sign-On (SSO):
- Student logs into BigBen CRM
- CRM generates JWT token
- Frontend calls this endpoint to verify token
- Grant board access without additional login
Iframe Integration:
- BigBen CRM embeds board in iframe
- CRM passes student token via postMessage
- Iframe verifies token and displays board
Mobile App Integration:
- Mobile app authenticates via BigBen CRM API
- Receives student token
- Verifies token before accessing boards
API Gateway Integration:
- API gateway validates student tokens
- Routes authenticated students to boards
- Maintains session across services

Security Considerations

Token Format:

JWT tokens signed with HS256 algorithm
Must include student_id and exp (expiration) claims
Shared secret between BigBen CRM and BoardAPI

Validation:

Token signature is verified using shared secret
Expiration time is checked (expired tokens are rejected)
Token must be from trusted issuer (BigBen CRM)

Best Practices:

Tokens should be short-lived (1-24 hours)
Use HTTPS for all token transmission
Never expose tokens in URLs or logs
Rotate shared secrets periodically

Error Responses

Invalid Token (401 Unauthorized):

json

{
  "statusCode": 401,
  "message": "Invalid or expired token",
  "error": "Unauthorized"
}

Malformed Request (400 Bad Request):

json

{
  "statusCode": 400,
  "message": ["user_token must be a string", "user_token should not be empty"],
  "error": "Bad Request"
}

Server Error (500 Internal Server Error):

json

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

Possible Errors

Status Code	Error	Description
`200`	Success	Token verified successfully
`400`	`Bad Request`	Missing or invalid `user_token` parameter
`401`	`Unauthorized`	Token is invalid, expired, or signature verification failed
`500`	`Internal Server Error`	Server error during verification

Integration Flow

┌─────────────────┐
│  BigBen CRM     │
│  (Legacy PHP)   │
└────────┬────────┘
         │ 1. Student logs in
         ▼
┌─────────────────┐
│ Generate JWT    │
│ (student_id,    │
│  exp, name)     │
└────────┬────────┘
         │ 2. Pass token to frontend
         ▼
┌─────────────────┐
│  Frontend       │
│  (React/Vue)    │
└────────┬────────┘
         │ 3. POST /auth/verify-student-token
         ▼
┌─────────────────┐
│  BoardAPI       │
│  Backend        │
└────────┬────────┘
         │ 4. Verify signature & expiration
         ▼
┌─────────────────┐
│  Return student │
│  data + valid   │
└─────────────────┘

Boards API - Create boards for lessons
WebSocket API - Real-time collaboration
User Authentication - Standard user login

Note: This endpoint is specific to BigBen CRM integration. For standard user authentication, use the User Authentication endpoints instead.

Authentication API ​

Organization Authentication ​

Generate Token ​

Response ​

Validate API Key ​

Response ​

Board Authentication ​

Validate Board Token ​

Response ​

User Authentication ​

Register ​

Response (201 Created) ​

Login ​

Response ​

Logout ​

Response ​

Password Reset ​

Request Reset ​

Reset Password ​

Email Verification ​

Resend Verification ​

Verify Email ​

External System Integration ​

Verify Student Token (BigBen CRM) ​

Endpoint ​

Request Body ​

Response ​

Response Fields ​

Example Requests ​

Use Cases ​

Security Considerations ​

Error Responses ​

Possible Errors ​

Integration Flow ​

Related Documentation ​

Authentication API

Organization Authentication

Generate Token

Response

Validate API Key

Response

Board Authentication

Validate Board Token

Response

User Authentication

Register

Response (201 Created)

Login

Response

Logout

Response

Password Reset

Request Reset

Reset Password

Email Verification

Resend Verification

Verify Email

External System Integration

Verify Student Token (BigBen CRM)

Endpoint

Request Body

Response

Response Fields

Example Requests

Use Cases

Security Considerations

Error Responses

Possible Errors

Integration Flow

Related Documentation