Skip to main content

Quickstart

Automate User Provisioning and Deprovisioning

Enterprises need to automatically provision and de-provision employee access to applications to ensure security. Scalekit simplifies this process by providing a single interface to your app, abstracting the complexities of various directory providers.

With Scalekit, you can:

  • Use Webhooks to listen for events from your customers' directory providers (e.g., user updates, group changes)
  • Use REST APIs to manage users, groups, and directories on demand

Scalekit enables you to sync user accounts with the latest data in the directory provider. This allows you to:

  • Create accounts for new hires during onboarding
  • Deactivate accounts when employees depart
  • Adjust access levels as employees change roles

User Provisioning with Scalekit's Directory API

Scalekit's Directory API allows you to fetch information about users, groups, and directories associated with an organization on-demand. This is useful for scenarios like running cron jobs to sync user and group data. In this guide, we'll demonstrate how to use the List Users in a Directory API to retrieve a list of users in a specific directory.

Before you begin, ensure that your organization has a directory set up in Scalekit.

Before diving in, ensure you have:

  1. A Scalekit account
  2. An organization with a configured directory in Scalekit (or use the default Test Organization)
  3. Access to the Scalekit Dashboard

Setting Up the SDK

Scalekit offers language-specific SDKs for fast SSO integration. Use the installation instructions below for your technology stack:

Setup SDK
npm install @scalekit-sdk/node

Navigate to the API Config tab in the Scalekit Dashboard to obtain your credentials. Store your credentials securely in a .env file:

.env
SCALEKIT_ENVIRONMENT_URL='https://b2b-app-dev.scalekit.com'
SCALEKIT_CLIENT_ID='<CLIENT_ID_FROM_SCALEKIT_DASHBOARD>'
SCALEKIT_CLIENT_SECRET='<SECRET_FROM_SCALEKIT_DASHBOARD>'

Initialize the SDK with your API credentials and make your first API call to list organizations.

Make your first SDK call
curl -L 'https://$ENV_URL/api/v1/organizations?page_size=5' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

Working with Directories

Retrieving a Directory

To begin syncing user and group data, first retrieve the directory associated with your organization:

Retrieve a Directory
// Get Directory using Organization ID and Directory ID
const { directory } = await scalekit.directory.getDirectory('<organization_id>', '<directory_id>');

// Get Directory using Organization ID
const { directory } =
  await scalekit.directory.getPrimaryDirectoryByOrganizationId('<organization_id>');

Listing Users in a Directory

Fetch users within a specific directory:

List Users in a Directory
const { users } = await scalekit.directory.listDirectoryUsers('<directory_id>');
//  users[0].email has the email of the first user in the directory

Example Use Case: When setting up a new customer account, you can use this function to automatically connect to their directory and start syncing user data.

See Directory User Object

Listing Groups

Retrieve groups within a directory:

List Groups in a Directory
const { groups } = await scalekit.directory.listDirectoryGroups('<directory_id>');

Example Use Case: You can use this function to implement role-based access control in your application, assigning permissions based on the groups a user belongs to.

Scalekit's Directory API provides a simple way to fetch user and group information on-demand. Refer to our API reference and examples to explore more capabilities.

Realtime User Provisioning with Webhooks

Create a Webhook Endpoint

To receive realtime events from directory providers, create a webhook endpoint and register it in the Scalekit dashboard.

app.post('/api/webhook/user-access', async (req, res) => {
  // Parse the JSON body of the request
  const event = req.body;
  const { email, name } = event.data;
  const headers = req.headers;
  const secret = process.env.SCALEKIT_WEBHOOK_SECRET;

  try {
    // Verify the webhook payload using the secret, headers, and event data
    await scalekit.verifyWebhookPayload(secret, headers, event);
  } catch (error) {
    // Return a 400 response if the signature is invalid
    return res.status(400).json({ error: 'Invalid signature' });
  }

  // Call a function to perform business logic
  await createUserAccount(email, name);

  // Return a JSON response with a status code of 201
  res.status(201).json({ message: 'User account created' });
});

In this example, the endpoint URL is https://www.hero-saas.app/api/webhook/user-access

When the endpoint receives an HTTP POST request with event data, it extracts the name and email from the payload and calls createUserAccount() to perform the necessary business logic — in this case, creating a user account.

Register Webhook Endpoint

First, navigate to the "Webhooks" tab in the Scalekit Dashboard. Click on the "+Add Endpoint" button and enter the endpoint URL along with a meaningful description. Finally, select the desired event types, such as scalekit.dir.user.*, to subscribe to the relevant events.

Click "Create." Once registered, the webhook endpoint will start receiving event payloads from the directory providers.

Refer to the API reference for the list of all available event types and setting up webhooks to explore testing webhooks with test endpoints.

Receive Event Payloads

Scalekit sends event payloads to your app for consumption and standardizes the payload structure across different directory providers your customers may use.Since we subscribed to user events, let's log an example of a new hire gaining access to your app when Scalekit sends a user creation event.

See Webhook Events for the list of all available event types.

You have now successfully created and registered a webhook endpoint, allowing your app to receive real-time events to automate user provisioning.


Is this page helpful? Yes No