Quickstart: First Login in 5 Minutes

Get a user authenticated via the Calimatic Auth headless API in under 5 minutes using the TypeScript SDK or raw HTTP.

Prerequisites

• Node.js 18 or later
• An app client registered in Calimatic Auth (you need the clientId and clientSecret)
• A user account with a verified email address

Step 1: Install the SDK

npm install @calimatic/auth

Step 2: Create the Client

Instantiate the HeadlessAuthClient with your server-side app credentials. Store these in environment variables — never in source code.

import { HeadlessAuthClient } from '@calimatic/auth/headless';

const client = new HeadlessAuthClient({
  baseUrl: 'https://auth.calimatic.com',
  clientId: process.env.CALIMATIC_CLIENT_ID!,
  clientSecret: process.env.CALIMATIC_CLIENT_SECRET!,
});

Step 3: Log In a User

Call client.auth.login with the user's email and password. The response is either a full token set or an MFA challenge.

const result = await client.auth.login({
  email: 'user@example.com',
  password: 'SecurePass1',
});

if ('mfaRequired' in result) {
  // MFA challenge — see the MFA section in the API Reference
  console.log('MFA required, token:', result.mfaToken);
} else {
  console.log('Logged in! Access token:', result.accessToken);
  console.log('User:', result.user.email);
}

Login response fields (when MFA is not required):

Step 4: Handle Errors

All SDK errors are instances of CalimaticAuthError. Check the code property to handle specific failure cases.

import { CalimaticAuthError, AuthErrorCode } from '@calimatic/auth/headless';

try {
  await client.auth.login({ email, password });
} catch (err) {
  if (err instanceof CalimaticAuthError) {
    switch (err.code) {
      case AuthErrorCode.INVALID_CREDENTIALS:
        console.error('Wrong email or password');
        break;
      case AuthErrorCode.ACCOUNT_LOCKED:
        console.error('Account locked — try again later');
        break;
      case AuthErrorCode.EMAIL_NOT_VERIFIED:
        console.error('Email address not verified');
        break;
      case AuthErrorCode.RATE_LIMITED:
        console.error('Too many requests — slow down');
        break;
      default:
        console.error('Auth error:', err.code, err.message);
    }
  }
}

Raw HTTP Example

You can call the API directly without the SDK. Every request must include the x-client-id and x-client-secret headers.

curl -X POST https://auth.calimatic.com/api/v1/auth/headless/login \
  -H "Content-Type: application/json" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -d '{"email": "user@example.com", "password": "SecurePass1"}'

Example success response:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR...",
  "idToken": "eyJhbGciOiJSUzI1NiIsInR...",
  "expiresAt": "2026-03-25T02:30:00.000Z",
  "user": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "firstName": "Jane",
    "lastName": "Doe"
  }
}

Next Steps

• Authentication Guide — Server-side credential storage, token lifecycle, and security best practices
• API Reference — All 19 headless auth endpoints with request/response schemas
• Error Code Reference — Complete list of AuthErrorCode values and when they are thrown