Optare v1.0 is now available. Get started →
SDKs
JavaScript Core

JavaScript Core SDK

@optare/optareid-js is the universal SDK that works in any JavaScript environment.

Installation

npm install @optare/optareid-js

Initialization

import { OptareClient } from '@optare/optareid-js';
 
const client = new OptareClient({
  baseUrl: 'https://id.optare.one',
  clientId: 'your_client_id',
  token: 'access_token', // Optional, for authenticated requests
});

Configuration Options

OptionTypeRequiredDescription
baseUrlstringYesOptare instance URL
clientIdstringYesYour OAuth client ID
clientSecretstringNoFor server-side only
tokenstringNoAccess token for API calls
refreshTokenstringNoFor automatic token refresh
onTokenRefreshfunctionNoCallback when tokens refresh
onAuthErrorfunctionNoCallback on auth errors

Namespaces

The SDK is organized into namespaces:

client.auth      // Authentication methods
client.org       // Organization management
client.license   // License/entitlement checking
client.admin     // Admin operations (server-side)
client.webhooks  // Webhook verification

Auth Namespace

getMe()

Get the current authenticated user.

const user = await client.auth.getMe();
// { id, email, name, avatarUrl }

logout()

Log out the current user.

await client.auth.logout();

Org Namespace

list()

List organizations the user belongs to.

const orgs = await client.org.list();
// [{ id, name, slug, role, logoUrl }]

create(name)

Create a new organization.

const org = await client.org.create('Acme Corp');
// { id, name, slug, role: 'owner' }

invite(email, role)

Invite a member to the current organization.

await client.org.invite('john@example.com', 'member');

License Namespace

check(feature)

Check if the user/org has access to a feature.

const hasAccess = await client.license.check('advanced-analytics');
if (hasAccess) {
  // Show premium feature
}

getEntitlements()

Get all entitlements for the current context.

const entitlements = await client.license.getEntitlements();
// [{ feature: 'sso', isEnabled: true, limit: 5, usage: 2 }]

Admin Namespace

Note: These methods require a client secret and should only be used server-side.

Products

// Create a product
const product = await client.admin.createProduct({
  name: 'Pro Plan',
  slug: 'pro',
  description: 'Professional features',
  features: ['sso', 'advanced-analytics'],
});
 
// List products
const products = await client.admin.listProducts();
 
// Get a product
const product = await client.admin.getProduct('pro');

Subscriptions

// Create a subscription
const subscription = await client.admin.createSubscription({
  organizationId: 'org_abc',
  productId: 'prod_xyz',
  totalSeats: 10,
  pricePerSeat: 20,
  billingCycle: 'monthly',
  status: 'active',
});
 
// List subscriptions
const subscriptions = await client.admin.listSubscriptions();

OAuth Clients

// Create an OAuth client
const oauthClient = await client.admin.createOAuthClient({
  name: 'My App',
  redirectUris: ['https://myapp.com/callback'],
  grantTypes: ['authorization_code', 'refresh_token'],
});

API Keys

// Create an API key
const apiKey = await client.admin.createApiKey({
  name: 'Backend Service',
  scopes: ['read:users', 'write:users'],
});
 
// List API keys
const keys = await client.admin.listApiKeys();
 
// Revoke an API key
await client.admin.revokeApiKey('key_abc123');

Webhooks

// Create a webhook
const webhook = await client.admin.createWebhook({
  url: 'https://myapp.com/webhooks',
  events: ['user.created', 'user.login'],
});

Webhooks Namespace

verify(payload, signature, secret)

Verify a webhook signature.

import { WebhookNamespace } from '@optare/optareid-js';
 
const isValid = WebhookNamespace.verify(
  rawBody,           // Request body as string
  signatureHeader,   // X-Optare-Signature header
  webhookSecret      // Your webhook secret
);
 
if (!isValid) {
  return res.status(401).json({ error: 'Invalid signature' });
}

Error Handling

import { 
  OptareError, 
  OptareAuthError, 
  OptareRateLimitError 
} from '@optare/optareid-js';
 
try {
  await client.auth.getMe();
} catch (error) {
  if (error instanceof OptareAuthError) {
    // Token expired or invalid
    console.log('Auth error:', error.code);
  } else if (error instanceof OptareRateLimitError) {
    // Rate limited
    console.log('Retry after:', error.retryAfter);
  } else if (error instanceof OptareError) {
    // Other API error
    console.log('API error:', error.message);
  }
}

Types

interface User {
  id: string;
  email: string;
  name?: string;
  avatarUrl?: string;
}
 
interface Organization {
  id: string;
  name: string;
  slug: string;
  logoUrl?: string;
}
 
interface OrganizationMember {
  id: string;
  name: string;
  slug: string;
  role: 'owner' | 'admin' | 'member' | 'guest';
}
 
interface Entitlement {
  feature: string;
  isEnabled: boolean;
  limit?: number;
  usage?: number;
}

Next Steps

OverviewReact