Authentication

Overview

OptiCRM APIs use two authentication methods:

1. Session-based (cookie) — For browser-based access via NextAuth.js
2. API Key — For server-to-server integrations

Session Authentication

All dashboard and portal pages use session-based auth via NextAuth.js JWT cookies.

Login

POST /api/auth/callback/staff-credentials
Content-Type: application/json
 
{
  "email": "admin@school.edu",
  "password": "your-password",
  "institutionSlug": "springfield"
}

Session Token

After login, a JWT cookie is set:

• Production: __Secure-authjs.session-token (secure, cross-subdomain)
• Development: authjs.session-token

The token contains: id, email, name, role, institutionId, institutionSlug

API Keys

For server-to-server integrations, generate API keys at Settings > API Keys.

Using API Keys

Include the key in the Authorization header:

GET /api/v1/entities/Student
Authorization: Bearer your-api-key-here

Rate Limits

Rate limit headers: X-RateLimit-Remaining

Password Reset API

Request Reset

POST /api/auth/forgot-password
Content-Type: application/json
 
{ "email": "user@school.edu" }

Response is always 200 (prevents email enumeration).

Validate Token

GET /api/auth/reset-password?token=abc123

Returns user info if token is valid.

Set New Password

POST /api/auth/reset-password
Content-Type: application/json
 
{
  "token": "abc123",
  "password": "new-secure-password"
}