@aceint/auth

Low-level TypeScript SDK for Aceint client-auth token issuance, refresh, and revoke flows.

Use This Package For

• issuing access and refresh tokens from your backend
• refreshing access tokens with a valid refresh token
• revoking a refresh token or token family

This package is intended for backend or server environments.

Do not use it directly from your frontend application. Frontend apps should call your backend, and your backend should call Aceint.

If you are integrating Aceint AI interview session APIs and want the SDK to manage token reuse and refresh on your backend, use @aceint/ai-interviews.

Requirements

• Node.js >=18
• Aceint client credentials from the Aceint Credentials tab

Installation

npm install @aceint/auth

Public Modes

The SDK uses explicit modes instead of raw URLs.

• dev → https://dev.aceint.ai/backend/api/v1
• prod → https://interview.aceint.ai/backend/api/v1

Use dev for development, QA, and integration testing.

Use prod for live production traffic.

Quick Start

import { SaasAuthClient } from '@aceint/auth';

const client = new SaasAuthClient({
  mode: 'dev',
  clientPublicId: process.env.ACEINT_CLIENT_PUBLIC_ID!,
  apiKey: process.env.ACEINT_API_KEY!,
  apiSecret: process.env.ACEINT_API_SECRET!,
});

const token = await client.getToken({ accessTtl: '15m' });
console.log(token.access_token);

Switch mode to prod when you are ready for production traffic.

Credential Mapping

Pass the credential values exactly as issued in Aceint:

• clientPublicId -> client_public_id
• apiKey -> ACEINT_API_KEY
• apiSecret -> ACEINT_API_SECRET

Store these values only in your backend environment or secret manager.

Supported TTL Values

• 15m
• 30m
• 1h
• 6h
• 24h

never is not supported for access_ttl. Access tokens always expire.

never applies only to credential-side refresh_ttl policies, not to access_ttl.

Token Lifetime Fields

Successful token responses include:

• expires_in: seconds until the access token expires
• refresh_expires_in: seconds until the refresh token expires

API

new SaasAuthClient(options)

Creates a client configured for one Aceint environment and one set of client credentials.

client.getToken(options?)

Uses the configured mode and credentials to call POST /client-auth/token.

const token = await client.getToken({ accessTtl: '15m' });

Allowed access TTL values for getToken: 15m, 30m, 1h, 6h, 24h.

client.refreshToken(input)

Calls POST /client-auth/refresh.

const nextToken = await client.refreshToken({
  refreshToken: token.refresh_token,
  accessTtl: '30m',
});

Allowed access TTL values for refreshToken: 15m, 30m, 1h, 6h, 24h.

client.revokeToken(input)

Calls POST /client-auth/revoke.

const revoked = await client.revokeToken({
  refreshToken: token.refresh_token,
  revokeFamily: true,
});

Example Flow

import { SaasAuthClient } from '@aceint/auth';

const client = new SaasAuthClient({
  mode: 'dev',
  clientPublicId: process.env.ACEINT_CLIENT_PUBLIC_ID!,
  apiKey: process.env.ACEINT_API_KEY!,
  apiSecret: process.env.ACEINT_API_SECRET!,
});

const token = await client.getToken({ accessTtl: '15m' });

// Use token.access_token against your protected Aceint APIs.

const refreshed = await client.refreshToken({
  refreshToken: token.refresh_token,
  accessTtl: '15m',
});

await client.revokeToken({
  refreshToken: refreshed.refresh_token,
  revokeFamily: true,
});

Recommended Integration Pattern

Use this package inside a reusable backend service layer such as AceintService.

Recommended request flow:

frontend -> your backend -> AceintService -> Aceint API

The SDK is intentionally thin. Your backend service layer should decide when to:

• reuse an active access token
• refresh an expired access token
• request a brand-new token with stored credentials
• attach Authorization: Bearer <access_token> to upstream Aceint API calls

For Aceint AI interview session integrations, @aceint/ai-interviews is the higher-level package built on top of this one.

Response Types

type TokenResponse = {
  access_token: string;
  refresh_token: string;
  expires_in: number;
  refresh_expires_in: number;
  token_type: 'Bearer';
};

type RevokeResponse = {
  success: boolean;
  revoked: Record<string, unknown> | null;
};

Error Handling

The SDK throws SaasAuthError for request failures. It preserves:

• backend message
• HTTP status code
• parsed response body when available

Notes

• This SDK does not cache tokens.
• This SDK does not auto-refresh tokens for you.
• This SDK is the low-level auth layer, not the full AI interview session SDK.