Node.js SDK Reference

Reference

ScalekitClient

client.getAuthorizationUrl(redirectUri, options?) -> string

📝 Description

Utility method to generate the OAuth 2.0 authorization URL to initiate the SSO authentication flow.

This method doesn’t make any network calls but instead generates a fully formed Authorization URL as a string that you can redirect your users to initiate authentication.

🔌 Usage

// Initiate Enterprise SSO authentication for a given org_id
const authUrl = scalekitClient.getAuthorizationUrl(
  'https://yourapp.com/auth/callback',
  {
    state: 'random-state-value',
    organizationId: 'org_123456'
  }
);
// Redirect user to authUrl

⚙️ Parameters

redirectUri: string - The URL where users will be redirected after authentication. Must match one of the redirect URIs configured in your Scalekit dashboard.

options: AuthorizationUrlOptions - Optional configuration for the authorization request

• scopes?: string[] - OAuth scopes to request (default: [‘openid’, ‘profile’, ‘email’])
• state?: string - Opaque value to maintain state between request and callback
• nonce?: string - String value used to associate a client session with an ID Token
• loginHint?: string - Hint about the login identifier the user might use
• domainHint?: string - Domain hint to identify which organization’s IdP to use
• connectionId?: string - Specific SSO connection ID to use for authentication
• organizationId?: string - Organization ID to authenticate against
• provider?: string - Social login provider (e.g., ‘google’, ‘github’, ‘microsoft’)
• codeChallenge?: string - PKCE code challenge for enhanced security
• codeChallengeMethod?: string - Method used to generate the code challenge (S256)
• prompt?: string - Controls authentication behavior (e.g., ‘login’, ‘consent’, ‘create’)

client.authenticateWithCode(code, redirectUri, options?) -> Promise<AuthenticationResponse>

📝 Description

Exchanges an authorization code for access tokens and user information.

This method completes the OAuth 2.0 authorization code flow by exchanging the code received in the callback for access tokens, ID tokens, and user profile information. Call this method in your redirect URI handler after receiving the authorization code.

🔌 Usage

app.get('/auth/callback', async (req, res) => {
  const { code } = req.query;

  const result = await scalekitClient.authenticateWithCode(
    code,
    'https://yourapp.com/auth/callback'
  );

  req.session.accessToken = result.accessToken;
  req.session.user = result.user;

  res.redirect('/dashboard');
});

⚙️ Parameters

code: string - The authorization code received in the callback URL after user authentication

redirectUri: string - The same redirect URI used in getAuthorizationUrl(). Must match exactly.

options: AuthenticationOptions - Optional authentication configuration

• codeVerifier?: string - PKCE code verifier to validate the code challenge (required if PKCE was used)

client.getIdpInitiatedLoginClaims(idpInitiatedLoginToken, options?) -> Promise<IdpInitiatedLoginClaims>

📝 Description

Extracts and validates claims from an IdP-initiated login token.

Use this method when handling IdP-initiated SSO flows, where the authentication is initiated from the identity provider’s portal rather than your application. This validates the token and returns the necessary information to initiate a new SP Initiated SSO workflow.

🔌 Usage

app.get('/auth/callback', async (req, res) => {
  const { idp_initiated_login } = req.query;

  if (idp_initiated_login) {
    const claims = await scalekitClient.getIdpInitiatedLoginClaims(idp_initiated_login);

    const authUrl = scalekitClient.getAuthorizationUrl(
      'https://yourapp.com/auth/callback',
      {
        connectionId: claims.connection_id,
        organizationId: claims.organization_id,
        loginHint: claims.login_hint,
        ...(claims.relay_state && { state: claims.relay_state })
      }
    );

    return res.redirect(authUrl);
  }
});

⚙️ Parameters

idpInitiatedLoginToken: string - The token received in the ‘idp_initiated_login’ query parameter

options: TokenValidationOptions - Optional token validation configuration

client.validateAccessToken(token, options?) -> Promise<boolean>

📝 Description

Validates the access token and returns a boolean result.

🔌 Usage

const isValid = await scalekitClient.validateAccessToken(token);
if (isValid) {
  // Token is valid, proceed with request
}

⚙️ Parameters

token: string - The token to be validated

options: TokenValidationOptions - Optional validation options for issuer, audience, and scopes

client.getLogoutUrl(options?) -> string

📝 Description

Returns the logout URL that can be used to log out the user.

🔌 Usage

const logoutUrl = scalekitClient.getLogoutUrl({
  postLogoutRedirectUri: 'https://example.com',
  state: 'some-state'
});

⚙️ Parameters

options: LogoutUrlOptions - Logout URL options

• idTokenHint?: string - The ID Token previously issued to the client
• postLogoutRedirectUri?: string - URL to redirect after logout
• state?: string - Opaque value to maintain state between request and callback

client.verifyWebhookPayload(secret, headers, payload) -> boolean

📝 Description

Verifies the authenticity and integrity of webhook payloads from Scalekit.

Use this method to validate webhook requests from Scalekit by verifying the HMAC signature. This ensures the webhook was sent by Scalekit and hasn’t been tampered with. The method checks the signature and timestamp to prevent replay attacks (5-minute tolerance window).

🔌 Usage

app.post('/webhooks/scalekit', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = process.env.SCALEKIT_WEBHOOK_SECRET;
  const headers = req.headers;
  const payload = req.body.toString();

  const isValid = scalekitClient.verifyWebhookPayload(secret, headers, payload);

  if (isValid) {
    const event = JSON.parse(payload);

    switch (event.type) {
      case 'user.created':
        console.log('New user created:', event.data);
        break;
      case 'connection.enabled':
        console.log('Connection enabled:', event.data);
        break;
    }

    res.status(200).send('Webhook received');
  }
});

⚙️ Parameters

secret: string - Your webhook signing secret from the Scalekit dashboard (format: ‘whsec_…’)

headers: Record<string, string> - The HTTP headers from the webhook request

payload: string - The raw webhook request body as a string

client.verifyInterceptorPayload(secret, headers, payload) -> boolean

📝 Description

Verifies the authenticity and integrity of interceptor payloads from Scalekit.

Use this method to validate HTTP interceptor requests from Scalekit by verifying the HMAC signature. This ensures the interceptor payload was sent by Scalekit and hasn’t been tampered with.

🔌 Usage

const isValid = scalekitClient.verifyInterceptorPayload(secret, headers, payload);

⚙️ Parameters

secret: string - Your interceptor signing secret from Scalekit Dashboard

headers: Record<string, string> - The HTTP headers from the interceptor request

payload: string - The raw interceptor request body as a string

Organizations

client.organization.createOrganization(name, options?) -> Promise<CreateOrganizationResponse>

📝 Description

Creates a new organization (tenant) in your Scalekit application.

Organizations represent your B2B customers. Each organization can have its own SSO connections, users, and configuration. Use the external ID to map Scalekit organizations to your internal system’s identifiers.

🔌 Usage

const org = await scalekitClient.organization.createOrganization(
  'Acme Corporation',
  { externalId: 'customer_12345' }
);

console.log('Organization ID:', org.organization.id);

⚙️ Parameters

name: string - Display name for the organization

options: object - Optional configuration

• externalId?: string - Your system’s unique identifier for this organization

client.organization.listOrganization(options?) -> Promise<ListOrganizationsResponse>

📝 Description

Retrieves a paginated list of all organizations in your Scalekit environment.

This method returns all organizations with support for pagination. Use this to display a list of your B2B customers, search for organizations, or perform bulk operations.

🔌 Usage

const response = await scalekitClient.organization.listOrganization({
  pageSize: 20
});

console.log('Organizations:', response.organizations);
console.log('Total:', response.totalSize);

⚙️ Parameters

options: object - Optional pagination parameters

• pageSize?: number - Number of organizations to return per page (default: 10, max: 100)
• pageToken?: string - Token for retrieving the next page of results

client.organization.getOrganization(id) -> Promise<GetOrganizationResponse>

📝 Description

Retrieves detailed information about a specific organization using its Scalekit ID.

Use this method to fetch complete organization details including display name, region, metadata, settings, and configuration.

🔌 Usage

const response = await scalekitClient.organization.getOrganization('org_12345');
const org = response.organization;

console.log('Organization:', org.displayName);
console.log('External ID:', org.externalId);

⚙️ Parameters

id: string - The Scalekit-generated organization identifier (format: “org_…”)

client.organization.getOrganizationByExternalId(externalId) -> Promise<GetOrganizationResponse>

📝 Description

Retrieves detailed information about an organization using your system’s external identifier.

This is particularly useful when you need to look up an organization using your own internal identifiers rather than Scalekit’s ID.

🔌 Usage

const response = await scalekitClient.organization.getOrganizationByExternalId('customer_12345');
const org = response.organization;

console.log('Scalekit ID:', org.id);
console.log('Organization:', org.displayName);

⚙️ Parameters

externalId: string - Your system’s unique identifier for the organization

client.organization.updateOrganization(id, organization) -> Promise<UpdateOrganizationResponse>

📝 Description

Updates an organization’s properties using its Scalekit ID.

Use this method to modify an organization’s display name, external ID, or custom metadata. Only the fields you specify in the update object will be changed.

🔌 Usage

const response = await scalekitClient.organization.updateOrganization('org_12345', {
  displayName: 'Acme Corporation (Updated)',
  metadata: {
    industry: 'Technology',
    size: 'Enterprise'
  }
});

⚙️ Parameters

id: string - The Scalekit organization identifier (format: “org_…”)

organization: PartialMessage<UpdateOrganization> - Object containing fields to update

client.organization.updateOrganizationByExternalId(externalId, organization) -> Promise<UpdateOrganizationResponse>

📝 Description

Updates an organization’s properties using your system’s external identifier.

This method provides the same functionality as updateOrganization but allows you to reference the organization using your own internal identifier.

🔌 Usage

const response = await scalekitClient.organization.updateOrganizationByExternalId(
  'customer_12345',
  { displayName: 'New Company Name' }
);

⚙️ Parameters

externalId: string - Your system’s unique identifier for the organization

organization: PartialMessage<UpdateOrganization> - Object containing fields to update

client.organization.deleteOrganization(organizationId) -> Promise<Empty>

📝 Description

Permanently deletes an organization from your Scalekit environment.

This operation removes the organization and all associated data including SSO connections, users, and settings. This action cannot be undone, so use with caution.

🔌 Usage

await scalekitClient.organization.deleteOrganization('org_12345');
console.log('Organization deleted successfully');

⚙️ Parameters

organizationId: string - The Scalekit organization identifier to delete

client.organization.generatePortalLink(organizationId) -> Promise<Link>

📝 Description

Creates a single use Admin Portal URL valid for 1 minute.

Once the generated admin portal URL is accessed or rendered, a temporary session of 6 hours is created to allow the admin to update SSO/SCIM configuration.

🔌 Usage

app.get('/admin/sso-settings', async (req, res) => {
  const organizationId = req.user.organizationId;

  const link = await scalekitClient.organization.generatePortalLink(organizationId);

  res.redirect(link.location);
});

⚙️ Parameters

organizationId: string - The Scalekit organization ID

client.organization.updateOrganizationSettings(organizationId, settings) -> Promise<GetOrganizationResponse>

📝 Description

Updates configuration settings and feature flags for an organization.

Use this method to enable or disable organization-level features such as SSO configuration, directory synchronization, session management, and other organization-specific settings.

🔌 Usage

const response = await scalekitClient.organization.updateOrganizationSettings('org_12345', {
  features: [
    { name: 'sso', enabled: true },
    { name: 'directory_sync', enabled: true }
  ]
});

⚙️ Parameters

organizationId: string - The Scalekit organization identifier

settings: OrganizationSettings - Configuration settings object

client.organization.upsertUserManagementSettings(organizationId, settings) -> Promise<OrganizationUserManagementSettings | undefined>

📝 Description

Creates or updates user management settings for an organization.

This method allows you to configure user-related constraints and policies at the organization level, such as setting a maximum number of allowed users.

🔌 Usage

const settings = await scalekitClient.organization.upsertUserManagementSettings(
  'org_12345',
  { maxAllowedUsers: 100 }
);

console.log('Max users allowed:', settings?.maxAllowedUsers);

⚙️ Parameters

organizationId: string - The Scalekit organization identifier

settings: OrganizationUserManagementSettingsInput - User management configuration

Connections

client.connection.getConnection(organizationId, id) -> Promise<GetConnectionResponse>

📝 Description

Retrieves complete configuration and status details for a specific SSO connection.

Use this method to fetch comprehensive information about an organization’s SSO connection, including provider settings, protocol details (SAML/OIDC), enabled status, and configuration metadata.

🔌 Usage

const response = await scalekitClient.connection.getConnection(
  'org_123456',
  'conn_abc123'
);

const conn = response.connection;
console.log('Provider:', conn.provider);
console.log('Type:', conn.type);
console.log('Status:', conn.enabled ? 'Enabled' : 'Disabled');

⚙️ Parameters

organizationId: string - The organization ID that owns the connection

id: string - The connection identifier to retrieve

client.connection.listConnectionsByDomain(domain) -> Promise<ListConnectionsResponse>

📝 Description

Lists all SSO connections associated with a specific email domain.

Use this method to discover which organizations have SSO configured for a particular domain. This is useful for implementing domain-based SSO routing where users are automatically directed to their organization’s SSO based on their email domain.

🔌 Usage

const response = await scalekitClient.connection.listConnectionsByDomain('acme.com');

if (response.connections.length > 0) {
  console.log('SSO available for domain acme.com');
  const connection = response.connections[0];
  console.log('Organization:', connection.organizationId);
}

⚙️ Parameters

domain: string - The email domain to search for (e.g., “acme.com”)

client.connection.listConnections(organizationId) -> Promise<ListConnectionsResponse>

📝 Description

Lists all SSO connections configured for an organization.

Retrieves all enterprise SSO connections (SAML, OIDC) that have been configured for the specified organization.

🔌 Usage

const response = await scalekitClient.connection.listConnections('org_123456');

console.log(`Found ${response.connections.length} connections`);
response.connections.forEach(conn => {
  console.log(`- ${conn.provider} (${conn.type}): ${conn.enabled ? 'Enabled' : 'Disabled'}`);
});

⚙️ Parameters

organizationId: string - The organization ID

client.connection.enableConnection(organizationId, id) -> Promise<ToggleConnectionResponse>

📝 Description

Enables an SSO connection for an organization.

Activates a previously disabled or newly configured SSO connection, allowing users from the organization to authenticate using this identity provider.

🔌 Usage

const response = await scalekitClient.connection.enableConnection(
  'org_123456',
  'conn_abc123'
);

console.log('Connection enabled:', response.connection.enabled);

⚙️ Parameters

organizationId: string - The organization ID

id: string - The connection ID to enable

client.connection.disableConnection(organizationId, id) -> Promise<ToggleConnectionResponse>

📝 Description

Disables an SSO connection for an organization.

Deactivates an SSO connection, preventing users from authenticating via this identity provider. Existing user sessions remain valid.

🔌 Usage

const response = await scalekitClient.connection.disableConnection(
  'org_123456',
  'conn_abc123'
);

console.log('Connection disabled:', !response.connection.enabled);

⚙️ Parameters

organizationId: string - The organization ID

id: string - The connection ID to disable

Users

client.user.createUserAndMembership(organizationId, options) -> Promise<CreateUserAndMembershipResponse>

📝 Description

Creates a new user and adds them as a member of an organization in a single operation.

This is the primary method for user provisioning. It creates the user account and establishes their membership in the specified organization. Optionally sends an invitation email to the user.

🔌 Usage

const response = await scalekitClient.user.createUserAndMembership(
  'org_123456',
  {
    email: 'john.doe@company.com',
    userProfile: {
      firstName: 'John',
      lastName: 'Doe'
    },
    sendInvitationEmail: true,
    metadata: {
      department: 'Engineering'
    }
  }
);

console.log('User created:', response.user.id);

⚙️ Parameters

organizationId: string - The organization ID to add the user to

options: CreateUserRequest - User creation configuration

• email: string - User’s email address (required)
• userProfile?: object - User profile information
• metadata?: Record<string, string> - Custom metadata
• sendInvitationEmail?: boolean - Whether to send invitation email

client.user.getUser(userId) -> Promise<GetUserResponse>

📝 Description

Retrieves comprehensive details about a specific user including their profile and memberships.

Use this method to fetch complete user information including their organization memberships, roles, profile details, and custom metadata.

🔌 Usage

const response = await scalekitClient.user.getUser('usr_123456');
const user = response.user;

console.log('User:', user.email);
console.log('Name:', user.userProfile?.firstName, user.userProfile?.lastName);
console.log('Organizations:', user.memberships?.length);

⚙️ Parameters

userId: string - The Scalekit-generated user identifier

client.user.listUsers(options?) -> Promise<ListUsersResponse>

📝 Description

Retrieves a paginated list of all users across your Scalekit environment.

This method returns all users in your environment regardless of organization membership.

🔌 Usage

const response = await scalekitClient.user.listUsers({
  pageSize: 20
});

console.log('Users:', response.users.length);
console.log('Total users:', response.totalSize);

⚙️ Parameters

options: object - Optional pagination parameters

• pageSize?: number - Number of users to return per page (10-100)
• pageToken?: string - Token for retrieving the next page

client.user.updateUser(userId, options) -> Promise<UpdateUserResponse>

📝 Description

Updates a user’s profile information and custom metadata.

Use this method to modify user profile details such as name or to update custom metadata associated with the user.

🔌 Usage

const response = await scalekitClient.user.updateUser('usr_123456', {
  userProfile: {
    firstName: 'John',
    lastName: 'Smith'
  },
  metadata: {
    department: 'Engineering',
    title: 'Senior Developer'
  }
});

⚙️ Parameters

userId: string - The Scalekit user identifier

options: UpdateUserRequestType - Object containing fields to update

client.user.deleteUser(userId) -> Promise<Empty>

📝 Description

Permanently deletes a user from your Scalekit environment.

This operation removes the user’s profile, all organization memberships, and related data. This action is irreversible.

🔌 Usage

await scalekitClient.user.deleteUser('usr_123456');
console.log('User deleted successfully');

⚙️ Parameters

userId: string - The Scalekit user identifier to delete

client.user.createMembership(organizationId, userId, options?) -> Promise<CreateMembershipResponse>

📝 Description

Adds an existing user as a member of a new organization with specified roles.

Use this method to grant organization access to users who already have accounts in your Scalekit environment.

🔌 Usage

const response = await scalekitClient.user.createMembership(
  'org_123456',
  'usr_789012',
  {
    roles: ['admin'],
    sendInvitationEmail: true
  }
);

⚙️ Parameters

organizationId: string - The organization ID to add the user to

userId: string - The user ID to add as a member

options: object - Optional membership configuration

• roles?: string[] - Array of role names
• metadata?: Record<string, string> - Custom metadata
• sendInvitationEmail?: boolean - Whether to send invitation email

client.user.deleteMembership(organizationId, userId) -> Promise<Empty>

📝 Description

Removes a user’s membership from a specific organization.

This operation revokes the user’s access to the specified organization while keeping their user account intact.

🔌 Usage

await scalekitClient.user.deleteMembership('org_123456', 'usr_789012');
console.log('User removed from organization');

⚙️ Parameters

organizationId: string - The organization ID to remove the user from

userId: string - The user ID to remove

client.user.updateMembership(organizationId, userId, options?) -> Promise<UpdateMembershipResponse>

📝 Description

Updates a user’s roles and metadata within a specific organization.

Use this method to modify a user’s permissions by changing their assigned roles or to update membership-specific metadata.

🔌 Usage

const response = await scalekitClient.user.updateMembership(
  'org_123456',
  'usr_789012',
  { roles: ['admin'] }
);

⚙️ Parameters

organizationId: string - The organization ID

userId: string - The user ID

options: object - Fields to update

• roles?: string[] - Array of role names (replaces existing)
• metadata?: Record<string, string> - Custom metadata

client.user.listOrganizationUsers(organizationId, options?) -> Promise<ListOrganizationUsersResponse>

📝 Description

Retrieves a paginated list of all users who are members of a specific organization.

This method returns all users with access to the specified organization, including their roles, membership details, and profiles.

🔌 Usage

const response = await scalekitClient.user.listOrganizationUsers('org_123456', {
  pageSize: 25
});

console.log('Organization users:', response.users.length);
console.log('Total members:', response.totalSize);

⚙️ Parameters

organizationId: string - The organization ID

options: object - Optional pagination parameters

• pageSize?: number - Number of users per page (1-100)
• pageToken?: string - Token for next page

client.user.resendInvite(organizationId, userId) -> Promise<ResendInviteResponse>

📝 Description

Resends an invitation email to a user for a specific organization.

Use this method when a user hasn’t received or has lost their invitation email.

🔌 Usage

const response = await scalekitClient.user.resendInvite('org_123456', 'usr_789012');
console.log('Invitation resent:', response.invite);

⚙️ Parameters

organizationId: string - The organization ID

userId: string - The user ID

Domains

client.domain.createDomain(organizationId, name, options?) -> Promise<CreateDomainResponse>

📝 Description

Adds a new domain configuration to an organization for SSO routing or user suggestions.

Domains serve two purposes based on their type:

• ORGANIZATION_DOMAIN: Used to identify the SSO connection for the organization
• ALLOWED_EMAIL_DOMAIN: Enables users to join the organization with automatic suggestions

Note: Public disposable domains (gmail.com, outlook.com, etc.) are automatically blocked for security.

🔌 Usage

const response = await scalekitClient.domain.createDomain(
  'org_123456',
  'acme.com',
  { domainType: 'ORGANIZATION_DOMAIN' }
);

console.log('Domain created:', response.domain.id);

⚙️ Parameters

organizationId: string - The organization ID

name: string - The domain name (e.g., “acme.com”)

options: object - Optional domain configuration

• domainType?: DomainType | string - Domain type: ‘ALLOWED_EMAIL_DOMAIN’ or ‘ORGANIZATION_DOMAIN’

client.domain.getDomain(organizationId, domainId) -> Promise<GetDomainResponse>

📝 Description

Retrieves detailed information about a specific domain configuration.

Returns complete domain details including the domain name, type, verification status, and timestamps.

🔌 Usage

const response = await scalekitClient.domain.getDomain(
  'org_123456',
  'domain_abc123'
);

console.log('Domain:', response.domain.domain);
console.log('Type:', response.domain.domainType);
console.log('Verified:', response.domain.verificationStatus);

⚙️ Parameters

organizationId: string - The organization ID

domainId: string - The domain ID

client.domain.listDomains(organizationId, options?) -> Promise<ListDomainResponse>

📝 Description

Retrieves all domain configurations for an organization.

Returns a complete list of domains configured for the organization, including both ORGANIZATION_DOMAIN and ALLOWED_EMAIL_DOMAIN types.

🔌 Usage

const response = await scalekitClient.domain.listDomains('org_123456');

console.log(`Found ${response.domains.length} domains`);
response.domains.forEach(domain => {
  console.log(`- ${domain.domain} (${domain.domainType}): ${domain.verificationStatus}`);
});

⚙️ Parameters

organizationId: string - The organization ID

options: object - Optional parameters

• domainType?: DomainType | string - Filter by domain type

client.domain.deleteDomain(organizationId, domainId) -> Promise<Empty>

📝 Description

Deletes a domain from an organization.

Removes the domain configuration from the organization. Users with email addresses from this domain will no longer be automatically routed to this organization’s SSO connection.

🔌 Usage

await scalekitClient.domain.deleteDomain('org_123456', 'domain_abc123');
console.log('Domain deleted successfully');

⚙️ Parameters

organizationId: string - The organization ID

domainId: string - The domain ID to delete

Directories

client.directory.listDirectories(organizationId) -> Promise<ListDirectoriesResponse>

📝 Description

Retrieves all SCIM directories configured for an organization.

Lists all directory sync connections that have been set up for the organization. Each directory represents a SCIM integration with an identity provider.

🔌 Usage

const response = await scalekitClient.directory.listDirectories('org_123456');

console.log(`Found ${response.directories.length} directories`);
response.directories.forEach(dir => {
  console.log(`- ${dir.provider}: ${dir.enabled ? 'Active' : 'Inactive'}`);
  console.log(`  Users: ${dir.userCount}, Groups: ${dir.groupCount}`);
});

⚙️ Parameters

organizationId: string - The organization ID

client.directory.getDirectory(organizationId, directoryId) -> Promise<GetDirectoryResponse>

📝 Description

Retrieves comprehensive details about a specific SCIM directory.

Fetches complete configuration and status information for a directory, including provider settings, synchronization status, user/group counts, and metadata.

🔌 Usage

const response = await scalekitClient.directory.getDirectory(
  'org_123456',
  'dir_abc123'
);

const dir = response.directory;
console.log('Provider:', dir.provider);
console.log('Status:', dir.enabled ? 'Active' : 'Inactive');
console.log('Users:', dir.userCount);

⚙️ Parameters

organizationId: string - The organization ID

directoryId: string - The directory ID

client.directory.getPrimaryDirectoryByOrganizationId(organizationId) -> Promise<Directory>

📝 Description

Retrieves the primary (first) directory for an organization.

This is a convenience method that fetches the first directory from the organization’s list of directories. Most organizations have a single directory.

🔌 Usage

const directory = await scalekitClient.directory.getPrimaryDirectoryByOrganizationId('org_123456');

console.log('Primary Directory:', directory.provider);
console.log('Users:', directory.userCount);

⚙️ Parameters

organizationId: string - The organization ID

client.directory.listDirectoryUsers(organizationId, directoryId, options?) -> Promise<ListDirectoryUsersResponse>

📝 Description

Lists users synchronized from an identity provider via SCIM directory sync.

Retrieves all users that have been synced from the organization’s IdP to your application.

🔌 Usage

const response = await scalekitClient.directory.listDirectoryUsers(
  'org_123456',
  'dir_abc123',
  { pageSize: 50 }
);

console.log(`Found ${response.totalSize} users`);

⚙️ Parameters

organizationId: string - The organization ID

directoryId: string - The directory ID

options: object - Optional filtering and pagination parameters

• pageSize?: number - Number of users per page (max: 100)
• pageToken?: string - Token for next page
• includeDetail?: boolean - Include full user profile details
• directoryGroupId?: string - Filter by group membership
• updatedAfter?: string - ISO 8601 timestamp

client.directory.listDirectoryGroups(organizationId, directoryId, options?) -> Promise<ListDirectoryGroupsResponse>

📝 Description

Retrieves groups synchronized from an identity provider via SCIM directory sync.

Fetches all groups that have been synced from the organization’s IdP to your application.

🔌 Usage

const response = await scalekitClient.directory.listDirectoryGroups(
  'org_123456',
  'dir_abc123',
  { pageSize: 30 }
);

console.log(`Found ${response.totalSize} groups`);

⚙️ Parameters

organizationId: string - The organization ID

directoryId: string - The directory ID

options: object - Optional filtering and pagination parameters

• pageSize?: number - Number of groups per page (max: 30)
• pageToken?: string - Token for next page
• includeDetail?: boolean - Include full group details
• updatedAfter?: string - ISO 8601 timestamp

client.directory.enableDirectory(organizationId, directoryId) -> Promise<ToggleDirectoryResponse>

📝 Description

Enables SCIM directory synchronization for an organization.

Activates automatic user and group synchronization from the organization’s identity provider.

🔌 Usage

const response = await scalekitClient.directory.enableDirectory(
  'org_123456',
  'dir_abc123'
);

console.log('Directory enabled:', response.directory.enabled);

⚙️ Parameters

organizationId: string - The organization ID

directoryId: string - The directory ID to enable

client.directory.disableDirectory(organizationId, directoryId) -> Promise<ToggleDirectoryResponse>

📝 Description

Disables SCIM directory synchronization for an organization.

Stops automatic user and group synchronization from the organization’s identity provider. Existing synced users and groups remain in your application.

🔌 Usage

const response = await scalekitClient.directory.disableDirectory(
  'org_123456',
  'dir_abc123'
);

console.log('Directory disabled:', !response.directory.enabled);

⚙️ Parameters

organizationId: string - The organization ID

directoryId: string - The directory ID to disable

Sessions

client.session.getSession(sessionId) -> Promise<SessionDetails>

📝 Description

Retrieves comprehensive metadata and status for a specific user session.

Fetches complete session information including authentication status, device details, IP address, geolocation, and expiration timelines.

🔌 Usage

const session = await scalekitClient.session.getSession('ses_123456');

console.log('Status:', session.status);
console.log('User:', session.userId);
console.log('Device:', session.deviceInfo);
console.log('Location:', session.geoLocation);

⚙️ Parameters

sessionId: string - The session identifier to retrieve

client.session.getUserSessions(userId, options?) -> Promise<UserSessionDetails>

📝 Description

Retrieves a paginated list of all sessions for a specific user across all devices and browsers.

Lists all user sessions with support for filtering by status and time range. Essential for displaying active sessions in account management.

🔌 Usage

const response = await scalekitClient.session.getUserSessions('usr_123456', {
  filter: { status: ['active'] },
  pageSize: 20
});

console.log(`User has ${response.totalSize} active sessions`);

⚙️ Parameters

userId: string - The user identifier

options: object - Optional pagination and filtering parameters

• pageSize?: number - Number of sessions per page
• pageToken?: string - Token for next page
• filter?: object - Filter criteria
  • status?: string[] - Filter by status (‘active’, ‘expired’, ‘revoked’, ‘logout’)
  • startTime?: Date - Include sessions created after this time
  • endTime?: Date - Include sessions created before this time

client.session.revokeSession(sessionId) -> Promise<RevokeSessionResponse>

📝 Description

Immediately invalidates a specific user session by setting its status to ‘revoked’.

Terminates a single session, forcing the user to re-authenticate on that specific device. The revocation is instantaneous and irreversible.

🔌 Usage

const response = await scalekitClient.session.revokeSession('ses_123456');
console.log('Session revoked at:', response.revokedAt);

⚙️ Parameters

sessionId: string - The session identifier to revoke

client.session.revokeAllUserSessions(userId) -> Promise<RevokeAllUserSessionsResponse>

📝 Description

Immediately invalidates all active sessions for a user across all devices and browsers.

Terminates all active sessions simultaneously, forcing the user to re-authenticate everywhere. Only active sessions are revoked.

🔌 Usage

const response = await scalekitClient.session.revokeAllUserSessions('usr_123456');

console.log(`Revoked ${response.totalCount} sessions`);

⚙️ Parameters

userId: string - The user identifier whose sessions should be revoked

Roles

client.role.createRole(role) -> Promise<CreateRoleResponse>

📝 Description

Creates a new environment-level role with specified permissions.

Environment roles are available across all organizations in your environment.

🔌 Usage

const response = await scalekitClient.role.createRole({
  name: 'content_editor',
  displayName: 'Content Editor',
  description: 'Can create and edit content',
  permissions: ['content:read', 'content:write', 'content:edit']
});

⚙️ Parameters

role: CreateRole - Role creation object containing:

• name: string - Unique role identifier
• displayName: string - Human-readable name
• description: string - Purpose and scope
• permissions: string[] - Array of permission strings
• baseRole?: string - Optional parent role for inheritance

client.role.getRole(roleName) -> Promise<GetRoleResponse>

📝 Description

Retrieves complete information for a specific environment role.

🔌 Usage

const response = await scalekitClient.role.getRole('content_editor');
console.log('Role:', response.role.displayName);
console.log('Permissions:', response.role.permissions);

⚙️ Parameters

roleName: string - Unique role identifier

client.role.listRoles() -> Promise<ListRolesResponse>

📝 Description

Lists all environment-level roles available in your Scalekit environment.

🔌 Usage

const response = await scalekitClient.role.listRoles();
response.roles.forEach(role => {
  console.log(`${role.displayName}: ${role.permissions.length} permissions`);
});

⚙️ Parameters

None

client.role.updateRole(roleName, role) -> Promise<UpdateRoleResponse>

📝 Description

Updates an existing environment role’s properties and permissions.

Only specified fields are updated. The new permission list replaces existing permissions.

🔌 Usage

await scalekitClient.role.updateRole('content_editor', {
  displayName: 'Content Editor (Updated)',
  permissions: ['content:read', 'content:write', 'content:edit', 'content:review']
});

⚙️ Parameters

roleName: string - Role to update

role: UpdateRole - Updated role properties

client.role.deleteRole(roleName, reassignRoleName?) -> Promise<Empty>

📝 Description

Deletes an environment role and reassigns its users to another role.

Cannot delete if dependent roles exist. Users must be reassigned before deletion. This operation is irreversible.

🔌 Usage

await scalekitClient.role.deleteRole('old_role', 'new_role');

⚙️ Parameters

roleName: string - Role to delete

reassignRoleName: string - Target role for user migration (optional)

client.role.getRoleUsersCount(roleName) -> Promise<GetRoleUsersCountResponse>

📝 Description

Gets the number of users assigned to an environment role.

Useful for capacity planning, security auditing, and impact assessment before role changes.

🔌 Usage

const response = await scalekitClient.role.getRoleUsersCount('admin');
console.log(`${response.count} users have admin role`);

⚙️ Parameters

roleName: string - Role to count users for

client.role.createOrganizationRole(orgId, role) -> Promise<CreateOrganizationRoleResponse>

📝 Description

Creates a new organization-specific role with custom permissions.

Organization roles are scoped to a specific organization for multi-tenant isolation.

🔌 Usage

await scalekitClient.role.createOrganizationRole('org_123456', {
  name: 'department_lead',
  displayName: 'Department Lead',
  description: 'Manages department members',
  permissions: ['dept:members:read', 'dept:members:invite']
});

⚙️ Parameters

orgId: string - Organization identifier

role: CreateOrganizationRole - Role configuration

client.role.getOrganizationRole(orgId, roleName) -> Promise<GetOrganizationRoleResponse>

📝 Description

Retrieves details for a specific organization role.

🔌 Usage

const response = await scalekitClient.role.getOrganizationRole(
  'org_123456',
  'department_lead'
);

console.log('Permissions:', response.role.permissions);

⚙️ Parameters

orgId: string - Organization identifier

roleName: string - Role name to retrieve

client.role.listOrganizationRoles(orgId) -> Promise<ListOrganizationRolesResponse>

📝 Description

Lists all roles available to an organization (environment + organization-specific).

Returns both environment-level roles and organization-scoped roles.

🔌 Usage

const response = await scalekitClient.role.listOrganizationRoles('org_123456');
response.roles.forEach(role => {
  console.log(`${role.displayName} (${role.scope})`);
});

⚙️ Parameters

orgId: string - Organization identifier

client.role.updateOrganizationRole(orgId, roleName, role) -> Promise<UpdateOrganizationRoleResponse>

📝 Description

Updates an organization role’s properties and permissions.

Only specified fields are updated. New permissions replace existing ones.

🔌 Usage

await scalekitClient.role.updateOrganizationRole('org_123456', 'department_lead', {
  permissions: ['dept:members:read', 'dept:members:invite', 'dept:members:remove']
});

⚙️ Parameters

orgId: string - Organization identifier

roleName: string - Role to update

role: UpdateRole - Updated role properties

client.role.deleteOrganizationRole(orgId, roleName, reassignRoleName?) -> Promise<Empty>

📝 Description

Deletes an organization role and reassigns its users.

Cannot delete if dependent roles exist. Users must be reassigned. Operation is irreversible.

🔌 Usage

await scalekitClient.role.deleteOrganizationRole(
  'org_123456',
  'old_role',
  'new_role'
);

⚙️ Parameters

orgId: string - Organization identifier

roleName: string - Role to delete

reassignRoleName: string - Target role for user migration (optional)

client.role.getOrganizationRoleUsersCount(orgId, roleName) -> Promise<GetOrganizationRoleUsersCountResponse>

📝 Description

Gets the number of users assigned to an organization role.

🔌 Usage

const response = await scalekitClient.role.getOrganizationRoleUsersCount(
  'org_123456',
  'admin'
);

console.log(`${response.count} admins in this organization`);

⚙️ Parameters

orgId: string - Organization identifier

roleName: string - Role to count users for

client.role.updateDefaultOrganizationRoles(orgId, defaultMemberRole) -> Promise<UpdateDefaultOrganizationRolesResponse>

📝 Description

Sets the default role automatically assigned to new organization members.

This is the role that is by default assigned to every new user added to this organization.

🔌 Usage

await scalekitClient.role.updateDefaultOrganizationRoles('org_123456', 'member');

⚙️ Parameters

orgId: string - Organization identifier

defaultMemberRole: string - Role name to assign by default

client.role.deleteOrganizationRoleBase(orgId, roleName) -> Promise<Empty>

📝 Description

Removes a role’s inheritance relationship, eliminating inherited permissions from base role.

Role retains only directly assigned permissions after removal. This action cannot be undone.

🔌 Usage

await scalekitClient.role.deleteOrganizationRoleBase('org_123456', 'custom_role');

⚙️ Parameters

orgId: string - Organization identifier

roleName: string - Role to remove inheritance from

Permissions

client.permission.createPermission(permission) -> Promise<CreatePermissionResponse>

📝 Description

Creates a new permission defining a specific action users can perform.

Permissions represent granular access controls following the ‘action:resource’ format.

🔌 Usage

await scalekitClient.permission.createPermission({
  name: 'read:invoices',
  description: 'View invoice details'
});

⚙️ Parameters

permission: CreatePermission - Permission object containing:

• name: string - Permission identifier (e.g., ‘read:documents’)
• description?: string - Explanation of what this permission grants

client.permission.getPermission(permissionName) -> Promise<GetPermissionResponse>

📝 Description

Retrieves complete information for a specific permission.

🔌 Usage

const response = await scalekitClient.permission.getPermission('read:invoices');
console.log('Description:', response.permission.description);

⚙️ Parameters

permissionName: string - Permission identifier

client.permission.listPermissions(pageToken?, pageSize?) -> Promise<ListPermissionsResponse>

📝 Description

Lists all permissions with pagination support.

View all permission definitions for auditing, role management, or understanding available access controls.

🔌 Usage

const response = await scalekitClient.permission.listPermissions();
response.permissions.forEach(perm => {
  console.log(`${perm.name}: ${perm.description}`);
});

⚙️ Parameters

pageToken: string - Token for retrieving the next page (optional)

pageSize: number - Number of permissions per page (max: 100) (optional)

client.permission.updatePermission(permissionName, permission) -> Promise<UpdatePermissionResponse>

📝 Description

Updates an existing permission’s attributes.

Note: The permission name itself cannot be changed as it serves as the immutable identifier.

🔌 Usage

await scalekitClient.permission.updatePermission('read:invoices', {
  name: 'read:invoices',
  description: 'View invoice details and history (updated)'
});

⚙️ Parameters

permissionName: string - Permission to update

permission: CreatePermission - Updated permission properties

client.permission.deletePermission(permissionName) -> Promise<Empty>

📝 Description

Permanently removes a permission.

Ensure no active roles depend on the permission before deletion.

🔌 Usage

await scalekitClient.permission.deletePermission('deprecated:feature');

⚙️ Parameters

permissionName: string - Permission identifier to delete

client.permission.listRolePermissions(roleName) -> Promise<ListRolePermissionsResponse>

📝 Description

Lists direct permissions assigned to a role (excluding inherited permissions).

Use this to view explicit permission assignments without inheritance from base roles.

🔌 Usage

const response = await scalekitClient.permission.listRolePermissions('editor');
console.log('Direct permissions:', response.permissions);

⚙️ Parameters

roleName: string - Role to examine

client.permission.addPermissionsToRole(roleName, permissionNames) -> Promise<AddPermissionsToRoleResponse>

📝 Description

Grants additional permissions to a role without removing existing assignments.

This is an incremental operation that adds new permissions while preserving existing ones.

🔌 Usage

await scalekitClient.permission.addPermissionsToRole('editor', [
  'read:documents',
  'write:documents',
  'edit:documents'
]);

⚙️ Parameters

roleName: string - Target role to enhance

permissionNames: string[] - Array of permission identifiers to add

client.permission.removePermissionFromRole(roleName, permissionName) -> Promise<Empty>

📝 Description

Revokes a specific permission from a role, restricting access for all assigned users.

Only affects direct assignments; doesn’t impact inherited permissions from base roles.

🔌 Usage

await scalekitClient.permission.removePermissionFromRole('editor', 'delete:documents');

⚙️ Parameters

roleName: string - Role to modify

permissionName: string - Permission to remove

client.permission.listEffectiveRolePermissions(roleName) -> Promise<ListEffectiveRolePermissionsResponse>

📝 Description

Lists all effective permissions for a role including both direct and inherited permissions.

This returns the complete set of capabilities available through the role hierarchy.

🔌 Usage

const response = await scalekitClient.permission.listEffectiveRolePermissions('senior_editor');

console.log('Total effective permissions:', response.permissions.length);

⚙️ Parameters

roleName: string - Role to analyze

Passwordless

client.passwordless.sendPasswordlessEmail(email, options?) -> Promise<SendPasswordlessResponse>

📝 Description

Send a passwordless authentication email with OTP or magic link.

🔌 Usage

const response = await scalekitClient.passwordless.sendPasswordlessEmail(
  'user@example.com',
  {
    template: 'SIGNIN',
    state: 'random-state',
    expiresIn: 3600
  }
);

console.log('Auth Request ID:', response.authRequestId);

⚙️ Parameters

email: string - The email address to send the passwordless link to

options: object - The options for sending the passwordless email

• template?: TemplateType - The template type (SIGNIN/SIGNUP)
• state?: string - Optional state parameter
• magiclinkAuthUri?: string - Optional auth URI for magic link
• expiresIn?: number - Optional expiration time in seconds (default: 3600)
• templateVariables?: Record<string, string> - Optional template variables

client.passwordless.verifyPasswordlessEmail(credential, authRequestId?) -> Promise<VerifyPasswordLessResponse>

📝 Description

Verify a passwordless authentication code or link token.

🔌 Usage

const response = await scalekitClient.passwordless.verifyPasswordlessEmail(
  { code: '123456' },
  'auth_request_id'
);

console.log('Email:', response.email);

⚙️ Parameters

credential: object - The credential to verify

• code?: string - The one-time code received via email
• linkToken?: string - The link token received via email

authRequestId: string - Optional auth request ID from the send response

client.passwordless.resendPasswordlessEmail(authRequestId) -> Promise<SendPasswordlessResponse>

📝 Description

Resend a passwordless authentication email.

🔌 Usage

const response = await scalekitClient.passwordless.resendPasswordlessEmail('auth_request_id');

⚙️ Parameters

authRequestId: string - The auth request ID from the original send response

WebAuthn

client.webauthn.listCredentials(userId) -> Promise<ListCredentialsResponse>

📝 Description

List all WebAuthn credentials for a user.

🔌 Usage

const response = await scalekitClient.webauthn.listCredentials('usr_123456');
console.log('Credentials:', response.credentials);

⚙️ Parameters

userId: string - The user ID to list credentials for

client.webauthn.updateCredential(credentialId, displayName) -> Promise<UpdateCredentialResponse>

📝 Description

Update a WebAuthn credential’s display name.

🔌 Usage

const response = await scalekitClient.webauthn.updateCredential(
  'cred_123',
  'My YubiKey'
);

⚙️ Parameters

credentialId: string - The credential ID to update

displayName: string - The new display name for the credential

client.webauthn.deleteCredential(credentialId) -> Promise<DeleteCredentialResponse>

📝 Description

Delete a WebAuthn credential.

🔌 Usage

const response = await scalekitClient.webauthn.deleteCredential('cred_123');
console.log('Deleted:', response.success);

⚙️ Parameters

credentialId: string - The credential ID to delete

Auth

client.auth.updateLoginUserDetails(connectionId, loginRequestId, user) -> Promise<Empty>

📝 Description

Updates user details for an ongoing authentication request.

If you are using Auth for MCP solution of Scalekit in “Bring your own Auth” mode, this method helps updating Scalekit with the currently logged in user details for the ongoing authentication request.

🔌 Usage

await scalekitClient.auth.updateLoginUserDetails(
  'conn_abc123',
  'login_xyz789',
  {
    email: 'john.doe@company.com',
    sub: 'unique_user_id_456',
  }
);

⚙️ Parameters

connectionId: string - The SSO connection ID being used for authentication

loginRequestId: string - The unique login request identifier from the auth flow

user: UserInput - User details to update

• email?: string - User’s email address
• sub?: string - Unique user identifier (subject)

---

Source: View on GitHub →

Last fetched: January 24, 2026