@cambo-auth/core

Official JavaScript / TypeScript SDK for Cambo Auth — a multi-tenant Identity & Access Management (IAM) platform.

What is Cambo Auth?

Cambo Auth is a hosted IAM platform that gives your application:

• Authentication — register, login, JWT access + refresh tokens
• Multi-tenancy — organizations, projects, and member management
• RBAC — roles, resources, and fine-grained permissions
• API Keys — machine-to-machine authentication
• Session control — list and revoke active sessions

No need to run your own auth server. Create an account, get an API key, and start in minutes.

Installation

npm install @cambo-auth/core
# or
pnpm add @cambo-auth/core
# or
yarn add @cambo-auth/core

Quick Start

import { createClient } from '@cambo-auth/core';

// Get your API key from https://core-auth.cambo.dev
// → Organizations → Your Project → API Keys → Create Key
const auth = createClient('sk_live_your_api_key_here');

// Register a user
const { accessToken, refreshToken } = await auth.auth.register({
  email: '[email protected]',
  password: 'SecurePass123',
  firstName: 'Alice',
});

// Login
const tokens = await auth.auth.login({
  email: '[email protected]',
  password: 'SecurePass123',
});

// Get current user
auth.setAccessToken(tokens.accessToken);
const me = await auth.auth.me();
console.log(me.email); // [email protected]

Setup (3 steps)

1. Create your project on Cambo Auth

1. Sign up at core-auth.cambo.dev
2. Create an Organization (your company / app name)
3. Create a Project inside the organization
4. Go to API Keys → create a secret key → copy it (shown once)

2. Install and initialize

import { createClient } from '@cambo-auth/core';

const auth = createClient('sk_live_...');

3. Configure CORS (for browser apps)

In the admin dashboard → your project → Allowed Origins → add your domain:

https://yourapp.com
http://localhost:3000

API Reference

Authentication

// Register a new user
await auth.auth.register({ email, password, firstName?, lastName? });

// Login
await auth.auth.login({ email, password });
// → { accessToken, refreshToken }

// Refresh access token (expires every 15 min)
await auth.auth.refresh(refreshToken);
// → { accessToken, refreshToken }

// Get current user profile
auth.setAccessToken(accessToken);
await auth.auth.me();
// → { id, email, firstName, lastName }

// Logout (revokes current session)
await auth.auth.logout();

Organizations

// List all organizations
await auth.organizations.list();

// Create an organization
await auth.organizations.create({ name, slug, description? });

// Get organization details
await auth.organizations.get(orgId);

// Add a member
await auth.organizations.addMember(orgId, userId, role?);
// role: 'OWNER' | 'ADMIN' | 'MEMBER'

Projects

// List projects in an organization
await auth.projects.list(orgId);

// Create a project
await auth.projects.create(orgId, { name, slug, description? });

// Get project details
await auth.projects.get(orgId, projectId);

// Update allowed CORS origins
await auth.projects.updateOrigins(orgId, projectId, ['https://yourapp.com']);

Resources & Permissions (RBAC)

// List resources
await auth.resources.list(projectId);

// Create a resource (auto-generates create/read/update/delete permissions)
await auth.resources.create(projectId, 'invoice', 'Invoice documents');

Roles

// List roles
await auth.roles.list(projectId);

// Create a role with permissions
await auth.roles.create(projectId, {
  name: 'Viewer',
  description: 'Read-only access',
  permissionIds: ['perm-uuid-1', 'perm-uuid-2'],
});

API Keys

// List API keys for a project
await auth.apiKeys.list(projectId);

// Create an API key (key shown ONCE — store it securely)
const { key } = await auth.apiKeys.create(projectId, {
  name: 'My Service',
  type: 'secret', // 'public' | 'secret'
});
console.log(key); // sk_live_...

// Revoke an API key
await auth.apiKeys.revoke(projectId, keyId);

Sessions

// List active sessions for the current user
await auth.sessions.list();
// → [{ id, ipAddress, userAgent, createdAt, expiresAt }]

// Revoke a session (sign out a device)
await auth.sessions.revoke(sessionId);

Token Refresh

Access tokens expire after 15 minutes. Refresh before expiry:

async function refreshTokens(refreshToken: string) {
  try {
    const { accessToken, refreshToken: newRefresh } =
      await auth.auth.refresh(refreshToken);

    localStorage.setItem('accessToken', accessToken);
    localStorage.setItem('refreshToken', newRefresh);
    auth.setAccessToken(accessToken);

    return accessToken;
  } catch {
    // Refresh expired — redirect to login
    localStorage.clear();
    window.location.href = '/login';
  }
}

Verifying Tokens in Your Backend

The access token is a standard JWT. Verify it locally without calling Cambo Auth on every request:

// Node.js
import * as jwt from 'jsonwebtoken';
const payload = jwt.verify(token, process.env.CAMBO_AUTH_JWT_SECRET);
// payload.sub = userId

# Python
import jwt
payload = jwt.decode(token, os.environ['CAMBO_AUTH_JWT_SECRET'], algorithms=['HS256'])

CAMBO_AUTH_JWT_SECRET is the JWT_ACCESS_SECRET value from your Cambo Auth server config.

TypeScript

Full TypeScript support is built in — no @types package needed.

import {
  CoreSDK,
  createClient,
  type TokenPair,
  type CoreSDKOptions,
  type RegisterPayload,
  type LoginPayload,
} from '@cambo-auth/core';

Advanced: Self-Hosted Server

If you run your own Cambo Auth instance:

import { CoreSDK } from '@cambo-auth/core';

const auth = new CoreSDK({
  baseUrl: 'https://your-own-server.com',
  apiKey: 'sk_live_...',
});

License

MIT © Cambo Auth