Organizations Module

Complete API reference for sso.organizations module - organization management, members, end-users, OAuth credentials, SMTP, domains, branding, audit logs, and webhooks

Updated Nov 28, 2025
Edit on GitHub

Organizations Module

The organizations module (sso.organizations) manages multi-tenant organizations, their members, end-users, OAuth credentials (BYOO), SMTP configuration, custom domains, branding, audit logs, and webhooks.

Core Organization Methods

Method: sso.organizations.create()

Signature:

create(payload: CreateOrganizationPayload): Promise<CreateOrganizationResponse>

Description: Create a new organization (requires authentication). The authenticated user becomes the organization owner. Returns JWT tokens with organization context, eliminating the need to re-authenticate after creation.

Parameters:

Name Type Description
payload CreateOrganizationPayload Organization creation payload
payload.slug string Unique organization slug (URL-friendly identifier)
payload.name string Organization display name

Returns: Promise<CreateOrganizationResponse> - Created organization with owner, membership, and JWT tokens

Response Fields:

Field Type Description
organization Organization Created organization object
owner User Owner user object
membership Membership Owner’s membership in the organization
access_token string JWT access token with organization context
refresh_token string Refresh token for session management

Example:

const result = await sso.organizations.create({
  slug: 'acme-corp',
  name: 'Acme Corporation'
});

// Store the new tokens with organization context
authStore.setTokens(result.access_token, result.refresh_token);

console.log(`Organization ${result.organization.name} created with status: ${result.organization.status}`);
console.log(`New JWT includes org claim: ${result.organization.slug}`);

Throws:

  • SsoApiError -
    • When slug is already taken
    • When slug format is invalid
    • When not authenticated (401)

Related:

Method: sso.organizations.list()

Signature:

list(params?: ListOrganizationsParams): Promise<OrganizationResponse[]>

Description: List all organizations the authenticated user is a member of.

Parameters:

Name Type Description
params ListOrganizationsParams (optional) Query parameters for filtering and pagination
params.status string (optional) Filter by status (‘active’, ‘pending’, ‘suspended’)
params.page number (optional) Page number (default: 1)
params.limit number (optional) Items per page (default: 20)

Returns: Promise<OrganizationResponse[]> - Array of organization responses

Response Fields (per OrganizationResponse):

Field Type Description
organization Organization Organization object
membership_count number Total number of members
service_count number Total number of services
role string Current user’s role (‘owner’, ‘admin’, ‘member’)

Example:

const orgs = await sso.organizations.list({
  status: 'active',
  page: 1,
  limit: 20
});
orgs.forEach(org => {
  console.log(`${org.organization.name} - ${org.role} - ${org.service_count} services`);
});

Throws:

  • SsoApiError - When user is not authenticated

Related:

Method: sso.organizations.get()

Signature:

get(orgSlug: string): Promise<OrganizationResponse>

Description: Get detailed information for a specific organization.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<OrganizationResponse> - Organization details

Example:

const org = await sso.organizations.get('acme-corp');
console.log(org.organization.name, org.membership_count);

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When organization not found
    • When user is not a member

Related:

Method: sso.organizations.update()

Signature:

update(orgSlug: string, payload: UpdateOrganizationPayload): Promise<OrganizationResponse>

Description: Update organization details. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
payload UpdateOrganizationPayload Update payload
payload.name string (optional) New organization name
payload.max_services number (optional) Maximum number of services allowed

Returns: Promise<OrganizationResponse> - Updated organization details

Example:

const updated = await sso.organizations.update('acme-corp', {
  name: 'Acme Corporation Inc.',
  max_services: 20
});
console.log('Organization updated:', updated.organization.name);

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When organization not found

Related:

Method: sso.organizations.delete()

Signature:

delete(orgSlug: string): Promise<void>

Description: Delete an organization and all its associated data. This is a destructive operation that cannot be undone. Requires ‘owner’ role. All related data will be cascade deleted including members, invitations, services, plans, subscriptions, OAuth credentials, and audit logs.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<void>

Example:

if (confirm('Are you sure? This cannot be undone!')) {
  await sso.organizations.delete('acme-corp');
  console.log('Organization deleted successfully');
}

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner role
    • When organization not found

Related:

Members Module

The members module (sso.organizations.members) manages organization members and their roles.

Method: sso.organizations.members.list()

Signature:

members.list(orgSlug: string): Promise<MemberListResponse>

Description: List all members of an organization.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<MemberListResponse> - Member list response with pagination metadata

Response Fields:

Field Type Description
members OrganizationMember[] Array of member objects
total number Total number of members

Example:

const result = await sso.organizations.members.list('acme-corp');
console.log(`Total members: ${result.total}`);
result.members.forEach(m => console.log(m.email, m.role));

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When organization not found
    • When user is not a member

Related:

Method: sso.organizations.members.updateRole()

Signature:

members.updateRole(orgSlug: string, userId: string, payload: UpdateMemberRolePayload): Promise<OrganizationMember>

Description: Update a member’s role. Requires ‘owner’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
userId string User ID to update
payload UpdateMemberRolePayload Role update payload
payload.role string New role (‘owner’, ‘admin’, ‘member’)

Returns: Promise<OrganizationMember> - Updated member details

Example:

await sso.organizations.members.updateRole('acme-corp', 'user-id', {
  role: 'admin'
});
console.log('User promoted to admin');

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner role
    • When member not found
    • When trying to change own role

Related:

Method: sso.organizations.members.remove()

Signature:

members.remove(orgSlug: string, userId: string): Promise<void>

Description: Remove a member from the organization. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
userId string User ID to remove

Returns: Promise<void>

Example:

await sso.organizations.members.remove('acme-corp', 'user-id');
console.log('Member removed successfully');

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When trying to remove self
    • When member not found

Related:

Method: sso.organizations.members.transferOwnership()

Signature:

members.transferOwnership(orgSlug: string, payload: TransferOwnershipPayload): Promise<void>

Description: Transfer organization ownership to another member. Requires ‘owner’ role. The current owner will be demoted to admin.

Parameters:

Name Type Description
orgSlug string Organization slug
payload TransferOwnershipPayload Transfer payload
payload.new_owner_user_id string User ID of new owner

Returns: Promise<void>

Example:

await sso.organizations.members.transferOwnership('acme-corp', {
  new_owner_user_id: 'new-owner-id'
});
console.log('Ownership transferred successfully');

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner role
    • When new owner is not a member

Related:

End-Users Module

The end-users module (sso.organizations.endUsers) manages organization’s customers (end-users with subscriptions).

Method: sso.organizations.endUsers.list()

Signature:

endUsers.list(orgSlug: string, params?: ListEndUsersParams): Promise<EndUserListResponse>

Description: List all end-users for an organization. Returns users who have identities (logged in) or subscriptions for the organization’s services.

Parameters:

Name Type Description
orgSlug string Organization slug
params ListEndUsersParams (optional) Query parameters for pagination and filtering
params.service_slug string (optional) Filter users by a specific service
params.page number (optional) Page number (default: 1)
params.limit number (optional) Items per page (default: 20)

Returns: Promise<EndUserListResponse> - Paginated list of end-users

Response Fields:

Field Type Description
users EndUser[] Array of end-user objects
total number Total number of end-users
page number Current page number
limit number Items per page

Example:

// List all end-users across all services
const allUsers = await sso.organizations.endUsers.list('acme-corp', {
  page: 1,
  limit: 20
});

// Filter by specific service
const serviceUsers = await sso.organizations.endUsers.list('acme-corp', {
  service_slug: 'my-app',
  page: 1,
  limit: 20
});
console.log(`Total end-users: ${allUsers.total}`);

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have admin/owner role
    • When organization not found

Related:

Method: sso.organizations.endUsers.get()

Signature:

endUsers.get(orgSlug: string, userId: string): Promise<EndUserDetailResponse>

Description: Get detailed information about a specific end-user.

Parameters:

Name Type Description
orgSlug string Organization slug
userId string User ID

Returns: Promise<EndUserDetailResponse> - End-user details with subscriptions, identities, and session count

Response Fields:

Field Type Description
user User User object
subscriptions Subscription[] Array of user’s subscriptions
identities Identity[] Array of linked social accounts
session_count number Number of active sessions

Example:

const endUser = await sso.organizations.endUsers.get('acme-corp', 'user-id');
console.log(`Active sessions: ${endUser.session_count}`);
console.log(`Subscriptions: ${endUser.subscriptions.length}`);

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have admin/owner role
    • When end-user not found

Related:

Method: sso.organizations.endUsers.revokeSessions()

Signature:

endUsers.revokeSessions(orgSlug: string, userId: string): Promise<RevokeSessionsResponse>

Description: Revoke all active sessions for an end-user. Requires admin or owner role. This will force the user to re-authenticate.

Parameters:

Name Type Description
orgSlug string Organization slug
userId string User ID

Returns: Promise<RevokeSessionsResponse> - Response with number of revoked sessions

Response Fields:

Field Type Description
revoked_count number Number of sessions revoked

Example:

const result = await sso.organizations.endUsers.revokeSessions('acme-corp', 'user-id');
console.log(`Revoked ${result.revoked_count} sessions`);

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have admin/owner role
    • When end-user not found

Related:

OAuth Credentials Module (BYOO)

The OAuth credentials module (sso.organizations.oauthCredentials) manages Bring Your Own OAuth (BYOO) credentials.

Method: sso.organizations.oauthCredentials.set()

Signature:

oauthCredentials.set(orgSlug: string, provider: OAuthProvider, payload: SetOAuthCredentialsPayload): Promise<OAuthCredentials>

Description: Set or update custom OAuth credentials for a provider. This enables white-labeled authentication using the organization’s own OAuth application. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
provider OAuthProvider OAuth provider (‘github’, ‘google’, ‘microsoft’)
payload SetOAuthCredentialsPayload OAuth credentials
payload.client_id string OAuth application client ID
payload.client_secret string OAuth application client secret

Returns: Promise<OAuthCredentials> - Created/updated credentials (without secret)

Example:

await sso.organizations.oauthCredentials.set('acme-corp', 'github', {
  client_id: 'Iv1.abc123',
  client_secret: 'secret-value'
});
console.log('GitHub OAuth credentials configured');

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When credentials are invalid

Related:

Method: sso.organizations.oauthCredentials.get()

Signature:

oauthCredentials.get(orgSlug: string, provider: OAuthProvider): Promise<OAuthCredentials>

Description: Get the configured OAuth credentials for a provider. The secret is never returned.

Parameters:

Name Type Description
orgSlug string Organization slug
provider OAuthProvider OAuth provider (‘github’, ‘google’, ‘microsoft’)

Returns: Promise<OAuthCredentials> - OAuth credentials (without secret)

Response Fields:

Field Type Description
provider string OAuth provider
client_id string OAuth application client ID
created_at string ISO timestamp of creation
updated_at string ISO timestamp of last update

Example:

const creds = await sso.organizations.oauthCredentials.get('acme-corp', 'github');
console.log(creds.client_id);

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When credentials not found

Related:

SMTP Configuration

Method: sso.organizations.setSmtp()

Signature:

setSmtp(orgSlug: string, config: SetSmtpRequest): Promise<{ message: string }>

Description: Configure SMTP settings for an organization. Only owners and admins can configure SMTP. The organization will use these settings for sending transactional emails (registration, password reset, etc.).

Parameters:

Name Type Description
orgSlug string Organization slug
config SetSmtpRequest SMTP configuration
config.host string SMTP server hostname
config.port number SMTP server port
config.username string SMTP username
config.password string SMTP password
config.from_email string From email address
config.from_name string From name

Returns: Promise<{ message: string }> - Success message

Example:

await sso.organizations.setSmtp('acme-corp', {
  host: 'smtp.gmail.com',
  port: 587,
  username: 'notifications@acme.com',
  password: 'your-app-password',
  from_email: 'notifications@acme.com',
  from_name: 'Acme Corp'
});
console.log('SMTP configured successfully');

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When SMTP configuration is invalid

Related:

Method: sso.organizations.getSmtp()

Signature:

getSmtp(orgSlug: string): Promise<SmtpConfigResponse>

Description: Get SMTP configuration for an organization. Only owners and admins can view SMTP settings. Password is never returned for security reasons.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<SmtpConfigResponse> - SMTP configuration (without password)

Response Fields:

Field Type Description
configured boolean Whether SMTP is configured
host string (optional) SMTP server hostname
port number (optional) SMTP server port
username string (optional) SMTP username
from_email string (optional) From email address
from_name string (optional) From name

Example:

const config = await sso.organizations.getSmtp('acme-corp');
if (config.configured) {
  console.log('SMTP host:', config.host);
}

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role

Related:

Method: sso.organizations.deleteSmtp()

Signature:

deleteSmtp(orgSlug: string): Promise<{ message: string }>

Description: Delete SMTP configuration for an organization. The organization will revert to using platform-level SMTP. Only owners and admins can delete SMTP settings.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<{ message: string }> - Success message

Example:

await sso.organizations.deleteSmtp('acme-corp');
// Organization now uses platform SMTP

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role

Related:

Custom Domains & Branding

Method: sso.organizations.setCustomDomain()

Signature:

setCustomDomain(orgSlug: string, request: SetCustomDomainRequest): Promise<DomainVerificationResponse>

Description: Set a custom domain for an organization. This enables white-labeling by allowing the organization to use their own domain (e.g., auth.acme.com) instead of the platform’s domain. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
request SetCustomDomainRequest Custom domain request
request.domain string Custom domain (e.g., ‘auth.acme.com’)

Returns: Promise<DomainVerificationResponse> - Domain verification instructions

Response Fields:

Field Type Description
domain string Custom domain
verification_token string Token to use for verification
verification_methods VerificationMethod[] Available verification methods

Example:

const verification = await sso.organizations.setCustomDomain('acme-corp', {
  domain: 'auth.acme.com'
});
console.log('Verification token:', verification.verification_token);
verification.verification_methods.forEach(method => {
  console.log(method.method, method.instructions);
});

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When domain is invalid

Related:

Method: sso.organizations.verifyCustomDomain()

Signature:

verifyCustomDomain(orgSlug: string): Promise<DomainVerificationResult>

Description: Verify a custom domain by checking DNS TXT record or HTTP file. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<DomainVerificationResult> - Verification result

Response Fields:

Field Type Description
verified boolean Whether domain was verified
message string Verification status message

Example:

const result = await sso.organizations.verifyCustomDomain('acme-corp');
if (result.verified) {
  console.log('Domain verified successfully!');
} else {
  console.log('Verification failed:', result.message);
}

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When domain not configured

Related:

Method: sso.organizations.getDomainConfiguration()

Signature:

getDomainConfiguration(orgSlug: string): Promise<DomainConfiguration>

Description: Get custom domain configuration for an organization.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<DomainConfiguration> - Domain configuration

Response Fields:

Field Type Description
custom_domain string (optional) Custom domain
domain_verified boolean Whether domain is verified
verification_token string (optional) Verification token

Example:

const config = await sso.organizations.getDomainConfiguration('acme-corp');
if (config.custom_domain && config.domain_verified) {
  console.log('Custom domain active:', config.custom_domain);
}

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When organization not found

Related:

Method: sso.organizations.deleteCustomDomain()

Signature:

deleteCustomDomain(orgSlug: string): Promise<void>

Description: Delete custom domain configuration. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<void>

Example:

await sso.organizations.deleteCustomDomain('acme-corp');
// Organization reverts to using platform domain

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role

Related:

Method: sso.organizations.updateBranding()

Signature:

updateBranding(orgSlug: string, request: UpdateBrandingRequest): Promise<BrandingConfiguration>

Description: Update branding configuration (logo and primary color). This controls the visual appearance of authentication pages. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
request UpdateBrandingRequest Branding configuration
request.logo_url string (optional) Logo URL
request.primary_color string (optional) Primary color (hex format)

Returns: Promise<BrandingConfiguration> - Updated branding configuration

Example:

await sso.organizations.updateBranding('acme-corp', {
  logo_url: 'https://cdn.acme.com/logo.png',
  primary_color: '#FF5733'
});

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When color format is invalid

Related:

Method: sso.organizations.getBranding()

Signature:

getBranding(orgSlug: string): Promise<BrandingConfiguration>

Description: Get branding configuration for an organization (requires authentication).

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<BrandingConfiguration> - Branding configuration

Response Fields:

Field Type Description
logo_url string (optional) Logo URL
primary_color string (optional) Primary color (hex format)

Example:

const branding = await sso.organizations.getBranding('acme-corp');
if (branding.logo_url) {
  console.log('Logo URL:', branding.logo_url);
}

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When organization not found

Related:

Method: sso.organizations.getPublicBranding()

Signature:

getPublicBranding(orgSlug: string): Promise<BrandingConfiguration>

Description: Get public branding configuration (no authentication required). This endpoint is used by login pages to display organization branding.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<BrandingConfiguration> - Branding configuration

Example:

// Can be called without authentication
const branding = await sso.organizations.getPublicBranding('acme-corp');
if (branding.logo_url) {
  document.querySelector('#logo').src = branding.logo_url;
}
if (branding.primary_color) {
  document.documentElement.style.setProperty('--primary-color', branding.primary_color);
}

Throws:

  • SsoApiError - When organization not found

Related:

Audit Logs Module

The audit logs module (sso.organizations.auditLogs) provides comprehensive audit trails of all administrative actions.

Method: sso.organizations.auditLogs.get()

Signature:

auditLogs.get(orgSlug: string, params?: AuditLogQueryParams): Promise<AuditLogResponse>

Description: Get audit logs for an organization. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
params AuditLogQueryParams (optional) Query parameters for filtering and pagination
params.action string (optional) Filter by specific action
params.target_type string (optional) Filter by target type
params.target_id string (optional) Filter by target ID
params.page number (optional) Page number (default: 1)
params.limit number (optional) Items per page (default: 50)

Returns: Promise<AuditLogResponse> - Paginated audit log response

Response Fields:

Field Type Description
logs AuditLog[] Array of audit log entries
total number Total number of logs
page number Current page number
limit number Items per page

Example:

// Get all audit logs
const logs = await sso.organizations.auditLogs.get('acme-corp');

// Filter by specific action
const userLogs = await sso.organizations.auditLogs.get('acme-corp', {
  action: 'user.role_updated',
  page: 1,
  limit: 20
});

// Filter by target
const serviceLogs = await sso.organizations.auditLogs.get('acme-corp', {
  target_type: 'service',
  target_id: 'service-123'
});

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role

Related:

Method: sso.organizations.auditLogs.getEventTypes()

Signature:

auditLogs.getEventTypes(orgSlug: string): Promise<EventTypeInfo[]>

Description: Get available audit event types for filtering. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<EventTypeInfo[]> - Array of event type information

Response Fields (per EventTypeInfo):

Field Type Description
value string Event type value
label string Human-readable label
category string Event category

Example:

const eventTypes = await sso.organizations.auditLogs.getEventTypes('acme-corp');

// Group by category for UI display
const byCategory = eventTypes.reduce((acc, event) => {
  if (!acc[event.category]) {
    acc[event.category] = [];
  }
  acc[event.category].push(event);
  return acc;
}, {});

console.log('Available audit event categories:', Object.keys(byCategory));

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role

Related:

Webhooks Module

The webhooks module (sso.organizations.webhooks) configures webhooks to receive real-time notifications about events.

Method: sso.organizations.webhooks.create()

Signature:

webhooks.create(orgSlug: string, webhook: CreateWebhookRequest): Promise<WebhookResponse>

Description: Create a new webhook for an organization. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
webhook CreateWebhookRequest Webhook creation payload
webhook.name string Webhook name
webhook.url string Webhook URL
webhook.events string[] Array of event types to subscribe to

Returns: Promise<WebhookResponse> - Created webhook details

Example:

const webhook = await sso.organizations.webhooks.create('acme-corp', {
  name: 'User Activity',
  url: 'https://api.example.com/webhooks',
  events: ['user.invited', 'user.joined', 'user.removed']
});
console.log('Created webhook:', webhook.id);

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When URL is invalid

Related:

Method: sso.organizations.webhooks.list()

Signature:

webhooks.list(orgSlug: string): Promise<WebhookListResponse>

Description: List all webhooks for an organization. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<WebhookListResponse> - List of webhooks with total count

Response Fields:

Field Type Description
webhooks WebhookResponse[] Array of webhook objects
total number Total number of webhooks

Example:

const { webhooks, total } = await sso.organizations.webhooks.list('acme-corp');
console.log(`Found ${total} webhooks`);
webhooks.forEach(w => console.log(w.name, w.is_active));

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role

Related:

Method: sso.organizations.webhooks.get()

Signature:

webhooks.get(orgSlug: string, webhookId: string): Promise<WebhookResponse>

Description: Get a specific webhook by ID. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
webhookId string Webhook ID

Returns: Promise<WebhookResponse> - Webhook details

Example:

const webhook = await sso.organizations.webhooks.get('acme-corp', 'webhook-123');
console.log('Webhook URL:', webhook.url);
console.log('Subscribed events:', webhook.events);

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When webhook not found

Related:

Method: sso.organizations.webhooks.update()

Signature:

webhooks.update(orgSlug: string, webhookId: string, updates: UpdateWebhookRequest): Promise<WebhookResponse>

Description: Update an existing webhook. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
webhookId string Webhook ID
updates UpdateWebhookRequest Partial webhook update payload
updates.name string (optional) Webhook name
updates.url string (optional) Webhook URL
updates.events string[] (optional) Array of event types
updates.is_active boolean (optional) Whether webhook is active

Returns: Promise<WebhookResponse> - Updated webhook details

Example:

// Update webhook URL and add new events
const updated = await sso.organizations.webhooks.update('acme-corp', 'webhook-123', {
  url: 'https://api.example.com/webhooks/v2',
  events: ['user.invited', 'user.joined', 'user.removed', 'user.role_updated']
});

// Deactivate webhook temporarily
await sso.organizations.webhooks.update('acme-corp', 'webhook-123', {
  is_active: false
});

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When webhook not found

Related:

Method: sso.organizations.webhooks.delete()

Signature:

webhooks.delete(orgSlug: string, webhookId: string): Promise<void>

Description: Delete a webhook. Requires ‘owner’ or ‘admin’ role. This will also delete all delivery history for this webhook.

Parameters:

Name Type Description
orgSlug string Organization slug
webhookId string Webhook ID

Returns: Promise<void>

Example:

await sso.organizations.webhooks.delete('acme-corp', 'webhook-123');
console.log('Webhook deleted successfully');

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When webhook not found

Related:

Method: sso.organizations.webhooks.getDeliveries()

Signature:

webhooks.getDeliveries(orgSlug: string, webhookId: string, params?: WebhookDeliveryQueryParams): Promise<WebhookDeliveryListResponse>

Description: Get delivery history for a specific webhook. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
webhookId string Webhook ID
params WebhookDeliveryQueryParams (optional) Query parameters for filtering and pagination
params.delivered boolean (optional) Filter by delivery status
params.event_type string (optional) Filter by event type
params.page number (optional) Page number (default: 1)
params.limit number (optional) Items per page (default: 20)

Returns: Promise<WebhookDeliveryListResponse> - Paginated webhook delivery response

Example:

// Get all delivery attempts
const deliveries = await sso.organizations.webhooks.getDeliveries('acme-corp', 'webhook-123');

// Get only failed deliveries
const failed = await sso.organizations.webhooks.getDeliveries('acme-corp', 'webhook-123', {
  delivered: false,
  page: 1,
  limit: 20
});

// Get deliveries for specific event type
const userEvents = await sso.organizations.webhooks.getDeliveries('acme-corp', 'webhook-123', {
  event_type: 'user.invited'
});

failed.deliveries.forEach(delivery => {
  console.log(`Failed: ${delivery.event_type} - ${delivery.delivery_error}`);
  console.log(`Next retry: ${delivery.next_retry_at}`);
});

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When webhook not found

Related:

Method: sso.organizations.webhooks.getEventTypes()

Signature:

webhooks.getEventTypes(orgSlug: string): Promise<EventTypeInfo[]>

Description: Get available webhook event types that can be subscribed to. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<EventTypeInfo[]> - Array of available event types with categories

Example:

const eventTypes = await sso.organizations.webhooks.getEventTypes('acme-corp');

// Group events by category for UI display
const byCategory = eventTypes.reduce((acc, event) => {
  if (!acc[event.category]) {
    acc[event.category] = [];
  }
  acc[event.category].push(event);
  return acc;
}, {});

// Display available events
Object.entries(byCategory).forEach(([category, events]) => {
  console.log(`\n${category}:`);
  events.forEach(e => console.log(`  - ${e.label} (${e.value})`));
});

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role

Related:

Risk Settings Module

The risk settings module (sso.organizations.riskSettings) manages adaptive authentication based on risk signals like impossible travel, device fingerprints, and velocity anomalies.

Method: sso.organizations.riskSettings.get()

Signature:

riskSettings.get(orgSlug: string): Promise<GetRiskSettingsResponse>

Description: Get risk settings configuration for an organization. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<GetRiskSettingsResponse> - Risk settings configuration

Response Fields:

Field Type Description
enforcement_mode string Risk enforcement mode (‘monitor’, ‘challenge’, ‘block’)
low_threshold number Low risk score threshold (0-100)
medium_threshold number Medium risk score threshold (0-100)
new_device_score number Risk points added for new device
impossible_travel_score number Risk points for impossible travel detection
velocity_threshold number Velocity detection threshold
velocity_score number Risk points for velocity anomalies

Example:

const settings = await sso.organizations.riskSettings.get('acme-corp');
console.log('Enforcement mode:', settings.enforcement_mode);
console.log('Risk thresholds - Low:', settings.low_threshold, 'Medium:', settings.medium_threshold);

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When organization not found

Related:

Method: sso.organizations.riskSettings.update()

Signature:

riskSettings.update(orgSlug: string, payload: UpdateRiskSettingsRequest): Promise<UpdateRiskSettingsResponse>

Description: Update risk settings for an organization. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
payload UpdateRiskSettingsRequest Risk settings update payload
payload.enforcement_mode string (optional) Risk enforcement mode (‘monitor’, ‘challenge’, ‘block’)
payload.low_threshold number (optional) Low risk score threshold (0-100)
payload.medium_threshold number (optional) Medium risk score threshold (0-100)
payload.new_device_score number (optional) Risk points for new device
payload.impossible_travel_score number (optional) Risk points for impossible travel
payload.velocity_threshold number (optional) Velocity detection threshold
payload.velocity_score number (optional) Risk points for velocity anomalies

Returns: Promise<UpdateRiskSettingsResponse> - Update confirmation

Response Fields:

Field Type Description
message string Confirmation message
settings object Updated risk settings

Example:

const result = await sso.organizations.riskSettings.update('acme-corp', {
  enforcement_mode: 'challenge',
  low_threshold: 30,
  medium_threshold: 70,
  new_device_score: 20,
  impossible_travel_score: 50,
  velocity_threshold: 10,
  velocity_score: 30
});
console.log(result.message);

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When threshold values are invalid

Related:

Method: sso.organizations.riskSettings.reset()

Signature:

riskSettings.reset(orgSlug: string): Promise<UpdateRiskSettingsResponse>

Description: Reset risk settings to default values. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<UpdateRiskSettingsResponse> - Reset confirmation with default values

Example:

const result = await sso.organizations.riskSettings.reset('acme-corp');
console.log('Risk settings reset to defaults');

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role

Related:

SIEM Module

The SIEM module (sso.organizations.siem) manages Security Information and Event Management integrations for streaming audit logs to external systems like Datadog, Splunk, or S3.

Method: sso.organizations.siem.create()

Signature:

siem.create(orgSlug: string, payload: CreateSiemConfigRequest): Promise<SiemConfigResponse>

Description: Create a new SIEM configuration for streaming audit logs. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
payload CreateSiemConfigRequest SIEM configuration payload
payload.name string Configuration name
payload.provider_type string SIEM provider (‘Datadog’, ‘Splunk’, ‘S3’, ‘Generic’)
payload.endpoint_url string SIEM endpoint URL
payload.api_key string (optional) API key for authentication
payload.batch_size number (optional) Number of events per batch (default: 100)

Returns: Promise<SiemConfigResponse> - Created SIEM configuration

Response Fields:

Field Type Description
id string SIEM configuration ID
name string Configuration name
provider_type string SIEM provider type
endpoint_url string Endpoint URL
enabled boolean Whether configuration is enabled
batch_size number Events per batch
created_at string ISO timestamp of creation
updated_at string ISO timestamp of last update

Example:

const config = await sso.organizations.siem.create('acme-corp', {
  name: 'Datadog Integration',
  provider_type: 'Datadog',
  endpoint_url: 'https://http-intake.logs.datadoghq.com/v1/input',
  api_key: 'dd-api-key',
  batch_size: 100
});
console.log('SIEM configuration created:', config.id);

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When endpoint URL is invalid

Related:

Method: sso.organizations.siem.list()

Signature:

siem.list(orgSlug: string): Promise<ListSiemConfigsResponse>

Description: List all SIEM configurations for an organization. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug

Returns: Promise<ListSiemConfigsResponse> - List of SIEM configurations

Response Fields:

Field Type Description
siem_configs SiemConfigResponse[] Array of SIEM configurations
total number Total number of configurations

Example:

const result = await sso.organizations.siem.list('acme-corp');
console.log(`Total SIEM configs: ${result.total}`);
result.siem_configs.forEach(config => {
  console.log(config.name, config.provider_type, config.enabled);
});

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role

Related:

Method: sso.organizations.siem.get()

Signature:

siem.get(orgSlug: string, configId: string): Promise<SiemConfigResponse>

Description: Get a specific SIEM configuration. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
configId string SIEM configuration ID

Returns: Promise<SiemConfigResponse> - SIEM configuration details

Example:

const config = await sso.organizations.siem.get('acme-corp', 'config-id');
console.log(config.name, config.endpoint_url);

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When configuration not found

Related:

Method: sso.organizations.siem.update()

Signature:

siem.update(orgSlug: string, configId: string, payload: UpdateSiemConfigRequest): Promise<SiemConfigResponse>

Description: Update a SIEM configuration. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
configId string SIEM configuration ID
payload UpdateSiemConfigRequest Update payload
payload.name string (optional) Configuration name
payload.endpoint_url string (optional) SIEM endpoint URL
payload.api_key string (optional) API key for authentication
payload.enabled boolean (optional) Whether configuration is enabled
payload.batch_size number (optional) Events per batch

Returns: Promise<SiemConfigResponse> - Updated SIEM configuration

Example:

const updated = await sso.organizations.siem.update('acme-corp', 'config-id', {
  enabled: false,
  batch_size: 200
});
console.log('SIEM configuration updated');

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When configuration not found

Related:

Method: sso.organizations.siem.delete()

Signature:

siem.delete(orgSlug: string, configId: string): Promise<void>

Description: Delete a SIEM configuration. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
configId string SIEM configuration ID

Returns: Promise<void>

Example:

await sso.organizations.siem.delete('acme-corp', 'config-id');
console.log('SIEM configuration deleted');

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When configuration not found

Related:

Method: sso.organizations.siem.test()

Signature:

siem.test(orgSlug: string, configId: string): Promise<TestConnectionResponse>

Description: Test connection to a SIEM endpoint by sending a test event. Verifies the configuration is working correctly. Requires ‘owner’ or ‘admin’ role.

Parameters:

Name Type Description
orgSlug string Organization slug
configId string SIEM configuration ID

Returns: Promise<TestConnectionResponse> - Test result

Response Fields:

Field Type Description
success boolean Whether test succeeded
message string Result message

Example:

const result = await sso.organizations.siem.test('acme-corp', 'config-id');
if (result.success) {
  console.log('Connection successful:', result.message);
} else {
  console.error('Connection failed:', result.message);
}

Throws:

  • SsoApiError -
    • When user is not authenticated
    • When user doesn’t have owner/admin role
    • When configuration not found

Related:

Type Definitions

Organization

interface Organization {
  id: string;
  slug: string;
  name: string;
  status: 'active' | 'pending' | 'suspended';
  max_services: number;
  created_at: string;
  updated_at: string;
}

OrganizationResponse

interface OrganizationResponse {
  organization: Organization;
  membership_count: number;
  service_count: number;
  role: 'owner' | 'admin' | 'member';
}

CreateOrganizationPayload

interface CreateOrganizationPayload {
  slug: string;
  name: string;
  owner_email: string;
}

UpdateOrganizationPayload

interface UpdateOrganizationPayload {
  name?: string;
  max_services?: number;
}

OrganizationMember

interface OrganizationMember {
  user_id: string;
  email: string;
  role: 'owner' | 'admin' | 'member';
  joined_at: string;
}

MemberListResponse

interface MemberListResponse {
  members: OrganizationMember[];
  total: number;
}

UpdateMemberRolePayload

interface UpdateMemberRolePayload {
  role: 'owner' | 'admin' | 'member';
}

TransferOwnershipPayload

interface TransferOwnershipPayload {
  new_owner_user_id: string;
}

EndUserListResponse

interface EndUserListResponse {
  users: EndUser[];
  total: number;
  page: number;
  limit: number;
}

EndUserDetailResponse

interface EndUserDetailResponse {
  user: User;
  subscriptions: Subscription[];
  identities: Identity[];
  session_count: number;
}

ListEndUsersParams

interface ListEndUsersParams {
  service_slug?: string;
  page?: number;
  limit?: number;
}

RevokeSessionsResponse

interface RevokeSessionsResponse {
  revoked_count: number;
}

OAuthCredentials

interface OAuthCredentials {
  provider: string;
  client_id: string;
  created_at: string;
  updated_at: string;
}

SetOAuthCredentialsPayload

interface SetOAuthCredentialsPayload {
  client_id: string;
  client_secret: string;
}

SetSmtpRequest

interface SetSmtpRequest {
  host: string;
  port: number;
  username: string;
  password: string;
  from_email: string;
  from_name: string;
}

SmtpConfigResponse

interface SmtpConfigResponse {
  configured: boolean;
  host?: string;
  port?: number;
  username?: string;
  from_email?: string;
  from_name?: string;
}

DomainConfiguration

interface DomainConfiguration {
  custom_domain?: string;
  domain_verified: boolean;
  verification_token?: string;
}

SetCustomDomainRequest

interface SetCustomDomainRequest {
  domain: string;
}

DomainVerificationResponse

interface DomainVerificationResponse {
  domain: string;
  verification_token: string;
  verification_methods: VerificationMethod[];
}

DomainVerificationResult

interface DomainVerificationResult {
  verified: boolean;
  message: string;
}

BrandingConfiguration

interface BrandingConfiguration {
  logo_url?: string;
  primary_color?: string;
}

UpdateBrandingRequest

interface UpdateBrandingRequest {
  logo_url?: string;
  primary_color?: string;
}

AuditLogResponse

interface AuditLogResponse {
  logs: AuditLog[];
  total: number;
  page: number;
  limit: number;
}

AuditLogQueryParams

interface AuditLogQueryParams {
  action?: string;
  target_type?: string;
  target_id?: string;
  page?: number;
  limit?: number;
}

EventTypeInfo

interface EventTypeInfo {
  value: string;
  label: string;
  category: string;
}

WebhookResponse

interface WebhookResponse {
  id: string;
  name: string;
  url: string;
  events: string[];
  is_active: boolean;
  created_at: string;
  updated_at: string;
}

WebhookListResponse

interface WebhookListResponse {
  webhooks: WebhookResponse[];
  total: number;
}

CreateWebhookRequest

interface CreateWebhookRequest {
  name: string;
  url: string;
  events: string[];
}

UpdateWebhookRequest

interface UpdateWebhookRequest {
  name?: string;
  url?: string;
  events?: string[];
  is_active?: boolean;
}

WebhookDeliveryListResponse

interface WebhookDeliveryListResponse {
  deliveries: WebhookDelivery[];
  total: number;
  page: number;
  limit: number;
}

WebhookDeliveryQueryParams

interface WebhookDeliveryQueryParams {
  delivered?: boolean;
  event_type?: string;
  page?: number;
  limit?: number;
}