Security Endpoints

Base URL: https://auth.calimatic.com/api/v1/auth/headless

Security endpoints use App Client authentication. These endpoints provide account lockout management, password policy retrieval, and manual account unlock capabilities.

Authentication

All endpoints in this group use App Client authentication:

Header	Value	Description
`x-client-id`	`cca_...`	Your app client ID
`x-client-secret`	`ccas_...`	Your app client secret

Endpoints Overview

Method	Endpoint	Description
`GET`	`/security/lockout-status?userId=...`	Get lockout status for a user
`GET`	`/security/password-policy`	Get the configured password policy
`POST`	`/security/unlock`	Unlock a locked user account

GET /api/v1/auth/headless/security/lockout-status

Get the lockout status for a specific user. Returns whether the account is currently locked, how long until it unlocks, and how many login attempts remain before lockout.

Authentication: App Client (x-client-id + x-client-secret)

Query Parameters

Parameter	Type	Required	Description
`userId`	string	Yes	ID of the user to check lockout status for

Response (200 OK)

{
  "locked": true,
  "remainingLockoutSeconds": 540,
  "attemptsRemaining": 0,
  "lockedUntil": "2025-01-15T10:09:00.000Z",
  "maxAttempts": 5,
  "lockoutDurationMinutes": 10
}

Response Fields

Field	Type	Description
`locked`	boolean	Whether the account is currently locked
`remainingLockoutSeconds`	number \| null	Seconds until the lockout expires (null if not locked)
`attemptsRemaining`	number	Number of failed login attempts remaining before lockout
`lockedUntil`	string \| null	ISO 8601 timestamp when lockout expires (null if not locked)
`maxAttempts`	number	Maximum failed attempts before account is locked
`lockoutDurationMinutes`	number	How long lockout lasts (in minutes)

Error Codes

Code	HTTP Status	Description
`USER_NOT_FOUND`	404	User does not exist
`INVALID_CLIENT`	401	App client credentials are missing or invalid
`RATE_LIMITED`	429	Request rate limit exceeded

SDK Method

const status = await client.security.lockoutStatus({ userId: 'user-uuid' });
if (status.locked) {
  console.log(`Locked for ${status.remainingLockoutSeconds}s`);
}

curl Example

curl -X GET "https://auth.calimatic.com/api/v1/auth/headless/security/lockout-status?userId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-client-id: cca_aBcDeFgHiJkL" \
  -H "x-client-secret: ccas_xYzAbCdEfGhI"

GET /api/v1/auth/headless/security/password-policy

Get the configured password policy for the organization. Returns the current password requirements including minimum length, required character classes, and other constraints. Use this to validate passwords client-side before submission.

Authentication: App Client (x-client-id + x-client-secret)

Request Body

None.

Response (200 OK)

{
  "minLength": 8,
  "requireUppercase": true,
  "requireLowercase": true,
  "requireDigits": true,
  "requireSpecialChars": false,
  "maxLength": 128
}

Response Fields

Field	Type	Description
`minLength`	number	Minimum password length
`requireUppercase`	boolean	Whether an uppercase letter is required
`requireLowercase`	boolean	Whether a lowercase letter is required
`requireDigits`	boolean	Whether a digit is required
`requireSpecialChars`	boolean	Whether a special character is required
`maxLength`	number (optional)	Maximum password length, if configured

Error Codes

Code	HTTP Status	Description
`INVALID_CLIENT`	401	App client credentials are missing or invalid
`RATE_LIMITED`	429	Request rate limit exceeded

SDK Method

const policy = await client.security.passwordPolicy();
console.log(`Minimum ${policy.minLength} characters required`);

curl Example

curl -X GET https://auth.calimatic.com/api/v1/auth/headless/security/password-policy \
  -H "x-client-id: cca_aBcDeFgHiJkL" \
  -H "x-client-secret: ccas_xYzAbCdEfGhI"

POST /api/v1/auth/headless/security/unlock

Unlock a locked user account. Clears the lockout state for the user, allowing them to attempt login again. Typically called by admin-level application clients responding to a support request.

Authentication: App Client (x-client-id + x-client-secret)

Request Body

Field	Type	Required	Description
`userId`	string	Yes	UUID of the user account to unlock

Response (200 OK)

Returns an empty body on success. The user may now attempt to log in.

{}

Error Codes

Code	HTTP Status	Description
`USER_NOT_FOUND`	404	User does not exist
`VALIDATION_ERROR`	400	userId is not a valid UUID
`INVALID_CLIENT`	401	App client credentials are missing or invalid

SDK Method

await client.security.unlock({ userId: 'user-uuid' });

curl Example

curl -X POST https://auth.calimatic.com/api/v1/auth/headless/security/unlock \
  -H "Content-Type: application/json" \
  -H "x-client-id: cca_aBcDeFgHiJkL" \
  -H "x-client-secret: ccas_xYzAbCdEfGhI" \
  -d '{
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'