API & SDKs
Authentication

Authentication API Reference

Complete API reference for authentication endpoints in Optare SSO.

Base URL

https://your-domain.com/api/auth

All authentication endpoints are prefixed with /api/auth.

Authentication

Most endpoints require authentication via session cookies or Bearer tokens.

Authorization: Bearer {access_token}

Or include session cookies in the request.

Sign Up

Create a new user account.

Endpoint

POST /api/auth/sign-up/email

Request Body

{
  email: string;      // Valid email address
  password: string;   // Minimum 8 characters
  name: string;       // User's full name
  callbackURL?: string; // Redirect after signup
}

Response

{
  user: {
    id: string;
    email: string;
    name: string;
    emailVerified: boolean;
    image: string | null;
    createdAt: string;
  };
  session: {
    id: string;
    userId: string;
    expiresAt: string;
    token: string;
  };
}

Example

const response = await fetch('https://your-domain.com/api/auth/sign-up/email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'SecurePassword123!',
    name: 'John Doe',
  }),
});
 
const { user, session } = await response.json();

Error Codes

CodeMessageDescription
400Invalid emailEmail format is invalid
400Password too shortPassword must be at least 8 characters
409Email already existsUser with this email already registered
500Internal server errorServer error occurred

Sign In

Authenticate an existing user.

Endpoint

POST /api/auth/sign-in/email

Request Body

{
  email: string;
  password: string;
  rememberMe?: boolean; // Extend session duration
  callbackURL?: string;
}

Response

{
  user: {
    id: string;
    email: string;
    name: string;
    emailVerified: boolean;
    image: string | null;
  };
  session: {
    id: string;
    userId: string;
    expiresAt: string;
    token: string;
  };
}

Example

const response = await fetch('https://your-domain.com/api/auth/sign-in/email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'SecurePassword123!',
    rememberMe: true,
  }),
  credentials: 'include', // Important for cookies
});
 
const { user, session } = await response.json();

Error Codes

CodeMessageDescription
401Invalid credentialsEmail or password incorrect
403Account suspendedUser account is suspended
429Too many attemptsRate limit exceeded

Sign Out

End the current session.

Endpoint

POST /api/auth/sign-out

Request Body

{
  // No body required
}

Response

{
  success: true
}

Example

await fetch('https://your-domain.com/api/auth/sign-out', {
  method: 'POST',
  credentials: 'include',
});

Get Session

Retrieve the current user session.

Endpoint

GET /api/auth/get-session

Response

{
  user: {
    id: string;
    email: string;
    name: string;
    emailVerified: boolean;
    image: string | null;
  };
  session: {
    id: string;
    userId: string;
    expiresAt: string;
    organizationId?: string; // If user is in an organization
  };
}

Example

const response = await fetch('https://your-domain.com/api/auth/get-session', {
  credentials: 'include',
});
 
const { user, session } = await response.json();

Error Codes

CodeMessageDescription
401UnauthorizedNo valid session found

Verify Email

Send email verification link.

Endpoint

POST /api/auth/send-verification-email

Request Body

{
  email: string;
  callbackURL?: string;
}

Response

{
  success: true;
  message: "Verification email sent"
}

Example

await fetch('https://your-domain.com/api/auth/send-verification-email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    callbackURL: 'https://yourapp.com/email-verified',
  }),
});

Verify Email Token

Verify email with token from email link.

Endpoint

POST /api/auth/verify-email

Request Body

{
  token: string; // Token from email link
}

Response

{
  success: true;
  user: {
    id: string;
    email: string;
    emailVerified: true;
  }
}

Forgot Password

Request password reset email.

Endpoint

POST /api/auth/forgot-password

Request Body

{
  email: string;
  redirectTo?: string;
}

Response

{
  success: true;
  message: "Password reset email sent"
}

Example

await fetch('https://your-domain.com/api/auth/forgot-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    redirectTo: 'https://yourapp.com/reset-password',
  }),
});

Reset Password

Reset password with token.

Endpoint

POST /api/auth/reset-password

Request Body

{
  token: string;      // Token from reset email
  password: string;   // New password
}

Response

{
  success: true;
  message: "Password reset successful"
}

Example

await fetch('https://your-domain.com/api/auth/reset-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    token: resetToken,
    password: 'NewSecurePassword123!',
  }),
});

Change Password

Change password for authenticated user.

Endpoint

POST /api/auth/change-password

Request Body

{
  currentPassword: string;
  newPassword: string;
}

Response

{
  success: true;
  message: "Password changed successfully"
}

Example

await fetch('https://your-domain.com/api/auth/change-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({
    currentPassword: 'OldPassword123!',
    newPassword: 'NewSecurePassword123!',
  }),
});

Update Profile

Update user profile information.

Endpoint

PATCH /api/auth/update-user

Request Body

{
  name?: string;
  image?: string; // URL to profile image
}

Response

{
  user: {
    id: string;
    email: string;
    name: string;
    image: string | null;
  }
}

Example

await fetch('https://your-domain.com/api/auth/update-user', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({
    name: 'Jane Doe',
    image: 'https://example.com/avatar.jpg',
  }),
});

List Sessions

Get all active sessions for the current user.

Endpoint

GET /api/auth/list-sessions

Response

{
  sessions: Array<{
    id: string;
    userId: string;
    expiresAt: string;
    ipAddress: string;
    userAgent: string;
    createdAt: string;
    isCurrent: boolean;
  }>
}

Example

const response = await fetch('https://your-domain.com/api/auth/list-sessions', {
  credentials: 'include',
});
 
const { sessions } = await response.json();

Revoke Session

Revoke a specific session.

Endpoint

POST /api/auth/revoke-session

Request Body

{
  sessionId: string;
}

Response

{
  success: true
}

Example

await fetch('https://your-domain.com/api/auth/revoke-session', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({
    sessionId: 'session_123',
  }),
});

Rate Limits

All authentication endpoints are rate-limited:

EndpointLimitWindow
Sign Up5 requests1 hour
Sign In10 requests15 minutes
Forgot Password3 requests1 hour
Verify Email5 requests1 hour
All Others100 requests15 minutes

When rate limited, you'll receive:

{
  error: "Too many requests",
  retryAfter: 900 // seconds
}

Webhooks

Subscribe to authentication events via webhooks. See Webhooks Documentation.

Available events:

  • user.created
  • user.updated
  • user.deleted
  • session.created
  • session.revoked
  • email.verified
  • password.changed

SDK Usage

Instead of calling the API directly, use our SDK:

import { authClient } from "~/lib/auth-client";
 
// Sign up
const { data, error } = await authClient.signUp.email({
  email: "user@example.com",
  password: "SecurePassword123!",
  name: "John Doe",
});
 
// Sign in
await authClient.signIn.email({
  email: "user@example.com",
  password: "SecurePassword123!",
});
 
// Get session
const { data: session } = authClient.useSession();
 
// Sign out
await authClient.signOut();
API ReferenceReadme