Skip to main content

Introduction

Scalekit API is modeled around the REST architecture style. That means, our API has predictable resource-oriented URLs, accepts form-encoded request bodies and produces JSON formatted responses, uses standard HTTP verbs and error codes.

Apart from REST APIs, we have published SDKs in some of the popular languages as shown below. You can use these SDKs and integrate with Scalekit much faster.

Some additional instructions around using our APIs

  • API Endpoint Host must use the Environment URL of the environment you are targeting.
  • API requests without appropriate authentication headers will fail with 401 status code.

Read below to understand more about how to authenticate the API calls and how to handle errors appropriately.

Just getting Started?

Refer to our Quick Start Guide

Setup SDK
npm install @scalekit-sdk/node
API Server Endpoint
# use the environment url found in API Config section
https://yourcompany.scalekit.com

# or, if you have enabled CNAME, you can use that too
https://auth.yoursaas.com

Authentication

Scalekit API uses OAuth2 Client Credentials based authentication. You can view and manage the necessary information from your API Config section in the Scalekit Dashboard.

You will need the following information to authenticate with Scalekit APIs

  • Client ID
  • Client Secret
  • Environment URL

You can obtain a secure token by making POST call to the https://<ENV_URL>/oauth/token endpoint and sending client_id and client_secret as part of the request body.

API Authentication
curl -L 'https://<ENV_URL>/oauth/token' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'client_id=skc_<client_id>' \
     -d 'client_secret=test_<client_secret>' \
     -d 'grant_type=client_credentials'
Response
{
  "access_token": "DCR5c8139165228a82e442445fe01c16",
  "token_type": "bearer",
  "expires_in": 1799
}

Using Access Token

The access_token is the OAuth access token you need to use for all subsequent API calls to Scalekit.

To make a request to one of our APIs, you need to include the access token in the Authorization header of the request as Bearer 'access_token'.

Please make sure that you keep your Client Secrets safely. Do not share your client secret in publicly accessible areas such as GitHub, client-side code, etc.

Our SDKs will automatically handle the API authentication and error handling to make the job of using our APIs much easier for you.

Using Bearer Token
$ curl --request GET "https://{ENV_URL}/api/v1/organizations" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {access_token}"

Error Handling

As mentioned earlier, Scalekit APIs return appropriate HTTP Status Codes along with the detailed error messages in case of invalid usage of APIs.

You can see the list of different HTTP Status Codes and the error message format in the right pane. We strongly recommend you to handle errors gracefully while writing code using our SDKs.

Error Codes
HTTP StatusDescription
200 or 201API request is successful
400The request was unacceptable, often due to missing a required parameter.
401Invalid Authentication Headers found in the request.
404Resource not found
429Too many requests hit the API too quickly. Retry the request after a cool-off period.
500 or 501 or 504Something went wrong at our end. These are usually a very rare occurrence. We automatically log these requests for alert our on-call engineers
401: Error Message
{
  "code": 16,
  "message": "Token empty",
  "details": [
    {
      "@type": "type.googleapis.com/scalekit.v1.errdetails.ErrorInfo",
      "error_code": "UNAUTHENTICATED"
    }
  ]
}

Single Sign-on

When you need one of your customers to login via Enterprise SSO, you can redirect them to Scalekit's Authorization URL with necessary details about the organization or the SSO connection. Scalekit will seamlessly deal with integrating with any Identity Provider and exchanges user information via SAML or OIDC or OAuth2.

More details about the Single Sign-on flow is described here

Authorization URL

Authorization URL initiates the Login flow with Scalekit.

Scalekit expects atleast one of the following parameters to be present. The parameters are used to determine the SSO connection used to Login in the user.

domain - Email domain of the user. Domain should be mapped to an Organization. The SSO connection from the org would be used to login to the app.

connection_id - ID of the SSO connection. If the Connection's status is active, the user will be redirected to the SSO Connection's identity provider configured.

organization_id - ID of Organization. The user will be redirected to the SSO connection's identity provider configured for that organization.

provider - ID of SSO Provider, Incase of Social Logins . e.g google

  • Parameters
  • client_idstringrequired

    The client ID string that you obtain from the API Credentials page

  • redirect_uristringrequired

    Determines where the response is sent. The value of this parameter must exactly match one of the authorized redirect values that you set in the API Credentials page (including the HTTP or HTTPS scheme, case, and trailing '/', if any).

  • domainstring

    Domain part of the email address that is mapped to an organization. Example. yourcustomer.com

  • connection_idstring

    Connection ID for which the SSO flow must be initiated for. If the Connection's status is active, the user will be redirected to the SSO Connection's identity provider configured

  • organization_idstring

    Organization ID for which the SSO flow must be initiated for. Based on the organization ID supplied, the user will be redirected to the SSO connection's identity provider configured for that organization.

  • providerstring

    Key for the Social SSO Provider. This is common to all Organizations. e.g. google, github, linkedin, gitlab, microsoft, salesforce

  • response_typestringrequired

    Value must be code

  • scopestringrequired

    Value must be openid email profile

  • statestring

    An opaque string that is round-tripped in the protocol; that is to say, it is returned back as-is as a URI parameter in the Basic flow. The state can be useful for correlating requests and responses. Because your redirect_uri can be guessed, using a state value can increase your assurance that an incoming connection is the result of an authentication request initiated by your app.

    State will be useful if you would like to retain some information about the user that you would like to use at the end of the login flow. E.g. deep link URL in your product to redirect the user to after a successful login.

    If you generate a random string or encode the hash of some client state (e.g., a cookie) in this state variable, you can validate the response to additionally ensure that the request and response originated in the same browser. This additional validation offers protection against attacks such as cross-site request forgery.

  • noncestring

    A random value generated by your app that enables replay protection.

  • login_hintstring

    When your app knows the email address of the user it is trying to authenticate, it can provide this parameter as a hint to the authentication server and Scalekit will pass this information to your customer's identity provider. Some identity providers prefill the login box with this value to make the login experience easier for the end user.

  • code_challengestring

    A challenge code generated from code_verifier that is required for PKCE flows. This is used ensure if the request was handled by the right parties. The string is stored by Scalekit to be used when validating the token request with a code_verifier. A code_challenge is generated as follows code_challenge = SHA256(code_verifier) .

  • code_challenge_methodstring

    The algorithm used to process the code challenge. The value should be S256

curl --request GET \
  --url 'https://$env_url/oauth/authorize
  ?client_id=skc_12344
  &redirect_uri=https%3A%2F%2Fmysaasapp.com%2Fredirect_uri
  &response_type=code
  &state=hf68uyjh2189iuhj56789
  &scope=openid email profile'
Response

User will be redirected to the appropriate Identity provider's login page based on either organization_id, or connection_id or domain.

Token URL

The code provided to the Redirect URI. Code can be exchanged for a ID Token containing the user details using the Token URL.

  • Parameters
  • codestringrequired

    The code received by the Redirect URI as part of the Authentication Response.

  • redirect_uristringrequired

    The redirect URI where this code was received. This will used to validate the code to make the code was infact generated for this redirect_uri.

  • client_idstringrequired

    Unique client ID that represents your application.

  • client_secretstringrequired

    The client secret to authorize the client.

  • grant_typestring

    Grant Type must be authorization_code.

  • code_verifierstring

    Used in PKCE flow, code_verifier is derived from the code_challenge presented at the Authorization Endpoint

curl --request POST \
  --url 'https://$env_url/oauth/token
  ?code=jhasd72
  &redirect_uri=https%3A%2F%2Fmysaasapp.com%2Fredirect_uri
  &client_id=skc_12344
  &client_secret=skc_prod_12441kjasad
  &grant_type=authorization_code'
Response
Loading...

Organization

Organization represents a customer or a tenant of your application. Use this to create enterprise Single Sign-on connections or Admin Portal links for your customers.

The Organization Object

  • Attributes
  • idstring

    Unique ID of the organization

  • display_namestring

    Display Name of the Organization

  • external_idstring

    Unique ID of this organization according to your system. You can store your unique ID for this organization in Scalekit's system and later use this to fetch Organization and Connection details. This is helpful if you don't want to persist Scalekit's Unique Identifiers in your database

  • metadatamap

    Set of key-value pairs that you can attach to the Organization object. This can be useful for storing additional information about the Organization in a structured format.

  • region_codeenum

    Region in which this organization data is stored in. By default, the environment's region_code is used to store this organization's data

    Possible values
  • US
  • EU
  • create_timestring

    Timestamp at which this organization record was created in RFC 3339 format

  • update_timestring

    Timestamp at which this organization record was last updated in RFC 3339 format

Organization Object
{
    "id": "org_2123312131125533",
    "display_name": "Acme Corp",
    "create_time": "2024-01-05T14:48:00.000Z",
    "external_id": "my_unique_id",
    "metadata": {
      "someKey": "somevalue"
    },
    "region_code": "US",
    "update_time": "…"
}

List All Organizations

Retrieve a paginated list of all organizations within the environment. Use the page_token from the response to access subsequent pages of results

  • Parameters
  • page_sizeintegerrequired

    Number of results to be returned. Max supported page_size is 30

  • page_tokenstring

    Token to access the next page of results

curl --request GET \
  --url 'https://$env_url/api/v1/organizations'
Response
Loading...

Create a New Organization

Create a new organization to represent a tenant within your application

  • Parameters
  • organizationrequired

    Organization details

curl --location 'https://$ENV_URL/api/v1/organizations' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "display_name": "<string>",
  "external_id": "<string>",
  "metadata": {
    "esse47": "<string>"
  }
}'
Response
Loading...

Retrieve Organization Information

Fetch detailed information about a specific organization using its unique identifier.

  • Parameters
  • idstringrequired

    Unique identifier to an Organization

  • external_idstring

    Unique identifier that links an Organization Object to your app's tenant, stored as an External ID

curl --request GET \
  --url 'https://$env_url/api/v1/organizations/{id}'
Response
Loading...

Update Organization Information

Update the details of an existing organization using its unique identifier

  • Parameters
  • idstringrequired

    Unique identifier of the organization to be updated

  • organizationrequired
  • external_idstring

    External ID of the organization to be updated

curl --location --request PATCH 'https://$ENV_URL/api/v1/organizations/{id}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "display_name": "<string>",
  "external_id": "<string>",
  "metadata": {
    "culpa_561": "<string>"
  }
}'
Response
Loading...

Update Organization Settings

Update the settings of the Organization. The settings include the SSO settings, Directory sync settings etc.

  • Parameters
  • idstringrequired

    Unique identifier of the organization to update settings

  • settingsrequired
curl --location --request PATCH 'https://$ENV_URL/api/v1/organizations/{organizations_id}/settings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'\
--data '{
    "features":
    [
        {
            "name": "sso",
            "enabled": false
        },
        {
            "name": "dir_sync",
            "enabled": true
        }
    ]
}'
Response
Loading...

Delete an Organization

Remove an existing organization from the environment using its unique identifier

  • Parameters
  • idstringrequired

    Unique identifier of the organization to delete

  • external_idstring

    External ID of the organization to delete

curl --location --request DELETE 'https://$ENV_URL/api/v1/organizations/{id}' \
--header 'Accept: application/json'
Response
Loading...

Admin Portal

Generates an Admin Portal link. The Admin Portal will be used by IT Admins to create and manage the SSO connection in their organization. The link generated via API will be valid for 1 week

  • Parameters
  • idstringrequired

    Organization ID

  • ssoboolean
  • directory_syncboolean
curl --location --request PUT 'https://$ENV_URL/api/v1/organizations/{id}/portal_links' \
--header 'Authorization: Bearer {access_token}'
Response
Loading...

SSO Connection

The Connection Object

  • Attributes
  • idstring

    Unique ID of the Connection

  • organization_idstring

    Organization ID to which this connection belongs to.

  • providerenum
    Possible values
  • OKTA
  • GOOGLE
  • MICROSOFT_AD
  • AUTH0
  • ONELOGIN
  • PING_IDENTITY
  • JUMPCLOUD
  • CUSTOM
  • statusenum
    Possible values
  • DRAFT
  • IN_PROGRESS
  • COMPLETED
  • enabledboolean
  • typeenum
    Possible values
  • OIDC
  • SAML
  • saml_configobject
    Child Attributes
  • sp_entity_idstring
  • sp_assertion_urlstring
  • sp_metadata_urlstring
  • idp_entity_idstring
  • idp_sso_urlstring
  • idp_metadata_urlstring
  • idp_certificatesarray object
    Child Attributes
  • certificatestring
  • expiry_timestring
  • issuerstring
  • create_timestring
  • idp_sso_request_bindingenum
    Possible values
  • POST
  • REDIRECT
  • idp_slo_urlstring
  • idp_slo_request_bindingenum
    Possible values
  • POST
  • REDIRECT
  • saml_signing_optionenum
    Possible values
  • NO_SIGNING
  • SAML_ONLY_RESPONSE_SIGNING
  • SAML_ONLY_ASSERTION_SIGNING
  • SAML_RESPONSE_ASSERTION_SIGNING
  • assertion_encryptedboolean
  • want_request_signedboolean
  • oidc_configobject
    Child Attributes
  • authorize_uristring
  • token_uristring
  • discovery_endpointstring
  • user_info_uristring
  • jwks_uristring
  • issuerstring
  • redirect_uristring
  • client_idstring
  • client_secretstring
  • scopesstring
  • pkce_enabledboolean
  • token_auth_typestring
  • create_timestring

    Timestamp at which this organization record was created in RFC 3339 format

  • update_timestring

    Timestamp at which this organization record was last updated in RFC 3339 format

Connection Object
Loading...

List All Connections

Get filtered connections: Retrieves a list of available connections in the environment based on specified criteria

  • Parameters
  • organization_idstring

    Unique identifier for the organization

  • domainstring

    Email domain to filter connections by organization

  • includestring

    placeholder

curl --request GET \
  --url 'https://$env_url/api/v1/connections'
Response
Loading...

Retrieve Connection Details

Obtain detailed information about a specific connection within an organization

  • Parameters
  • organization_idstringrequired

    Organization ID for the Connection.

  • idstringrequired

    Connection ID. Unique ID for the connection

curl --location 'https://$ENV_URL/api/v1/organizations/{organization_id}/connections/{id}' \
--header 'Accept: application/json'
Response
Loading...

Disable a Connection for an Organization

Deactivate an existing SSO connection for the specified organization.

  • Parameters
  • organization_idstringrequired

    Unique identifier of the organization associated with the connection

  • idstringrequired

    Unique identifier for the connection to be toggled

curl --location --request PATCH 'https://$ENV_URL/api/v1/organizations/{organization_id}/connections/{id}:disable' \
--header 'Accept: application/json'
Response
Loading...

Enable a Connection for an Organization

Activate an existing SSO connection for the specified organization

  • Parameters
  • organization_idstringrequired

    Unique identifier of the organization associated with the connection

  • idstringrequired

    Unique identifier for the connection to be toggled

curl --location --request PATCH 'https://$ENV_URL/api/v1/organizations/{organization_id}/connections/{id}:enable' \
--header 'Accept: application/json'
Response
Loading...

Enable a Connection for an Organization

Activate an existing SSO connection for the specified organization

  • Parameters
  • organization_idstringrequired

    Unique identifier of the organization associated with the connection

  • idstringrequired

    Unique identifier for the connection to be toggled

curl --location --request PATCH 'https://$ENV_URL/api/v1/organizations/{organization_id}/connections/{id}:enable' \
--header 'Accept: application/json'
Response
Loading...

Directory

The Directory object represents a connection to a directory provider. You can programmatically enable or disable directories for an organization using the Directory API. Scalekit synchronizes and stores the users and groups from connected directories. The Directory API allows you to fetch users and groups from the directory on demand.

The Directory Object

  • Attributes
  • idstring

    Unique identifier for the directory.

  • namestring

    The name of the directory.

  • directory_providerenum

    The directory provider.

    Possible values
  • OKTA
  • directory_typeenum

    The protocol used to connect to the directory.

    Possible values
  • SCIM
  • directory_endpointstring

    The URL endpoint for connecting to the directory.

  • enabledboolean

    Indicates if the directory connection is enabled.

  • statusenum

    The status of the directory connection.

    Possible values
  • DRAFT
  • organization_idstring

    The ID of the organization the directory belongs to.

  • sourcestring

    The source of the directory.

  • last_synced_atstring

    Timestamp of when the directory was last synced in RFC 3339 format.

  • total_usersinteger

    The total number of users in the directory.

  • total_groupsinteger

    The total number of groups in the directory.

  • mappingsarray

    An array of attribute mappings between the directory and Scalekit.

    Attributes
    • keystring

      The attribute key in the directory.

    • map_tostring

      The attribute to map to in Scalekit.

    • display_namestring

      The display name for the mapped attribute.

  • attribute_mappingsobject

    Object containing attribute mappings.

    Attributes
    • attributesarray

      Array of attribute mappings.

      Attributes
      • keystring

        The attribute key.

      • map_tostring

        The attribute to map to.

  • role_assignmentsobject

    Object containing role assignments.

    Attributes
    • assignmentsarray

      Array of role assignments.

      Attributes
      • group_idstring

        The ID of the group to assign the role to.

      • role_idstring

        The ID of the role to assign.

  • secretsarray

    An array of secrets associated with the directory.

    Attributes
    • idstring

      The ID of the secret.

    • directory_idstring

      The ID of the directory the secret belongs to.

    • secret_suffixstring

      The suffix of the secret.

    • statusenum

      The status of the secret.

      Possible values
    • INACTIVE
    • create_timestring

      Timestamp of when the secret was created in RFC 3339 format.

    • expire_timestring

      Timestamp of when the secret expires in RFC 3339 format.

    • last_used_timestring

      Timestamp of when the secret was last used in RFC 3339 format.

  • statsobject

    Object containing directory statistics.

    Attributes
    • total_usersinteger

      The total number of users in the directory.

    • total_groupsinteger

      The total number of groups in the directory.

    • user_updated_atstring

      Timestamp of when the user stats were last updated in RFC 3339 format.

    • group_updated_atstring

      Timestamp of when the group stats were last updated in RFC 3339 format.

Directory Object
Loading...

The Directory User Object

  • Attributes
  • idstring

    Unique identifier for the directory user. This is a system-generated unique identifier that distinguishes each user within the directory.

  • organization_idstring

    Identifier of the organization to which the user belongs. This helps in segregating users across different organizational contexts.

  • dp_idstring

    External identifier from the identity provider (IdP). This is the original user identifier as recognized by the source directory or identity management system.

  • preferred_usernamestring

    The preferred username as defined by the identity provider. This may differ from the email address and is often used for login purposes.

  • emailstring

    Primary email address associated with the user. Used for communication and often as a unique identifier.

  • activeboolean

    Indicates the current status of the user account. When true, the user is active and can access the system; when false, the account is disabled.

  • namestring

    Full name of the user, typically combining given name and family name.

  • rolesarray

    List of roles assigned to the user, defining their permissions and access levels within the system.

    Role Object Attributes
    • rolestring

      Machine-readable identifier for the role.

    • namestring

      Human-readable name of the role.

  • groupsarray

    Groups to which the user belongs, typically used for organizational or access management purposes.

    Group Object Attributes
    • idstring

      Unique identifier of the group.

    • namestring

      Name of the group.

  • given_namestring

    User's first name or given name as provided by the identity provider.

  • family_namestring

    User's last name or family name as provided by the identity provider.

  • nicknamestring

    Informal or alternative name for the user, often used for casual identification.

  • picturestring

    URL pointing to the user's profile picture or avatar.

  • phone_numberstring

    Primary contact phone number for the user, including country code.

  • addressobject

    Structured address information for the user.

    Address Object Attributes
    • postal_codestring

      Postal or ZIP code for the user's address.

    • statestring

      State or region of the user's address.

    • formattedstring

      Full, human-readable address string.

  • custom_attributesobject

    Flexible key-value store for additional user-specific attributes not covered by standard fields.

  • raw_attributesobject

    Unmodified payload directly from the directory provider, preserving all original attributes.

Directory User Object
Loading...

The Directory Group Object

  • Attributes
  • idstring

    Unique identifier for the directory group. This is a system-generated identifier that uniquely distinguishes each group within the directory.

  • display_namestring

    Human-readable name of the group, typically used for display purposes in user interfaces and reports.

  • total_usersinteger

    Total number of users currently assigned to this group. Provides a quick count of group membership.

  • updated_atstring

    Timestamp indicating the last modification time of the group in RFC 3339 format. Useful for tracking recent changes to group composition.

Directory Group Object
Loading...

Enable a Directory

Enables a directory, allowing it to be used for user management and authentication

  • Parameters
  • organization_idstringrequired

    Unique identifier of the organization

  • idstringrequired

    Unique identifier of the directory within the organization

curl --location --request PATCH 'https://$ENV_URL/api/v1/organizations/{organizations_id}/directories/{directory_id}:enable'\
--header 'Authorization: Bearer <ACCESS_TOKEN>'
Response
Loading...

Get Directory

Retrieves detailed information about a specific directory within an organization. This endpoint allows you to view the properties and configuration of a connected Directory Provider

  • Parameters
  • organization_idstringrequired

    Unique identifier to an Organization

  • idstringrequired

    Unique identifier of a Directory

curl --location 'https://$ENV_URL/api/v1/organizations/{organizations_id}/directories/{directory_id}' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'
Get Primary Directory (Alternative)
async function getPrimaryDirectoryByOrganizationId(organizationId) {
  const { directory } =
    await scalekit.directory.getPrimaryDirectoryByOrganizationId(organizationId);
  console.log('Directory ID:', directory.id);
  return directory;
}

const organizationId = 'org_33247113199762954';
const directory = await getDirectory(organizationId);
Response
Loading...

List Users in Directory

Retrieves a list of all users within a specified directory for an organization. This endpoint allows you to view user accounts associated with your connected Directory Providers.

  • Parameters
  • organization_idstringrequired

    Unique identifier of the organization

  • directory_idstringrequired

    Unique identifier of the directory within the organization

  • page_sizeinteger

    Number of users to return per page. Maximum value is 30. If not specified, defaults to 10

  • page_tokenstring

    Token for pagination. Use the value returned in the 'next_page_token' field of the previous response to retrieve the next page of results

  • include_detailboolean

    If set to true, the response will include the full user payload with all available details. If false or not specified, only essential user information will be returned

  • directory_group_idstring

    Filter users by their membership in a specific directory group

  • updated_afterstring

    Filter users that were updated after the specified timestamp. Use RFC 3339 format

curl --location 'https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/<organization_id>/directories/<directory_id>/users' \
--header 'Authorization: Bearer <SCALEKIT_ACCESS_TOKEN>'
Response
Loading...

List Groups in Directory

Retrieves a list of all groups within a specified directory for an organization. This endpoint allows you to view the group structures within your connected Directory Providers.

  • Parameters
  • organization_idstringrequired

    Unique identifier of the organization

  • directory_idstringrequired

    Unique identifier of the directory within the organization

  • page_sizeinteger

    Number of groups to return per page (default: 10, max: 30)

  • page_tokenstring

    Token for pagination. Use the value returned in the previous response to fetch the next page of results

  • updated_afterstring

    Filter groups updated after the specified timestamp (RFC 3339 format)

  • include_detailboolean

    If true, include the full group payload in the response; otherwise, only basic information is returned (default: false)

curl --location 'https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/<organization_id>/directories/<directory_id>/groups' \
--header 'Authorization: Bearer <SCALEKIT_ACCESS_TOKEN>'
Response
Loading...

List Directories for an Organization

  • Parameters
  • organization_idstringrequired

    Unique identifier for the organization. This ID is used to retrieve directories associated with the specified organization.

curl --location 'https://$ENV_URL/api/v1/organizations/{organizations_id}/directories'\
--header 'Authorization: Bearer <ACCESS_TOKEN>'
Response
Loading...

Disable a Directory

Disables a directory, preventing it from being used for user management and authentication

  • Parameters
  • organization_idstringrequired

    Unique identifier of the organization

  • idstringrequired

    Unique identifier of the directory within the organization

curl --location --request PATCH 'https://$ENV_URL/api/v1/organizations/{organizations_id}/directories/{directory_id}:disable'\
--header 'Authorization: Bearer <ACCESS_TOKEN>'
Response
Loading...

Webhooks

A webhook (also called a web callback or HTTP push API) is a way for Scalekit to provide your applications with real-time information. A webhook delivers data to your applications as it happens, meaning you get data immediately, unlike typical APIs where you would need to poll for data very frequently to get it in real-time. Events represent specific actions or changes, while webhooks are the mechanism used to deliver these event notifications to your specified endpoint.

By leveraging webhooks, you can build responsive and dynamic integrations that react immediately to changes in Scalekit System, enabling you to keep your systems in sync and automate user lifecycle management and other related use cases.

Event Object

Every webhook payload has two key components: Event Metadata and Event Data.

  • Event Metadata
  • spec_versionstring

    Version of the event specification (currently '1').

  • categorystring

    Indicates the event category (Example: 'dir' for directory-related events).

  • typestring

    Specifies the exact event type (Example: 'scalekit.dir.user.create' for user creation).

  • occured_atstring

    Timestamp of when the event occurred.

  • sourcestring

    The origin of the event (always 'scalekit' in this case).

  • objectstring

    The type of object affected (Example: 'DirectoryUser').

  • Event Data
  • dataobject

    Contains latest object data after the event.

Sample Event Payload
{
  "spec_version": "1",
  "category": "dir",
  "type": "scalekit.dir.user.create",
  "occured_at": "2024-08-21T10:20:17.072Z",
  "source": "scalekit",
  "object": "DirectoryUser",
  "data": {
    // Event Data
  }
}

scalekit.dir.user.create

This webhook is triggered when a new directory user is created.

  • Event Data
  • idstring

    Unique ID of the Directory User.

  • organization_idstring

    Unique ID of the Organization to which this directory user belongs.

  • dp_idstring

    Unique ID of the User in the Directory Provider (IdP) system.

  • preferred_usernamestring

    Preferred username of the directory user.

  • emailstring

    Email of the directory user.

  • activeboolean

    Indicates if the directory user is active.

  • namestring

    Fully formatted name of the directory user.

  • rolesarray

    Array of roles assigned to the directory user.

    Child Attributes
  • rolestring

    Role of the directory user.

  • namestring

    Name of the directory user.

  • groupsarray

    Array of groups to which the directory user belongs.

    Child Attributes
  • idstring

    ID of the directory group.

  • namestring

    Name of the directory group.

  • given_namestring

    Given name of the directory user.

  • family_namestring

    Family name of the directory user.

  • nicknamestring

    Nickname of the directory user.

  • picturestring

    URL of the directory user's profile picture.

  • phone_numberstring

    Phone number of the directory user.

  • addressobject

    Address of the directory user.

    Child Attributes
  • postal_codestring

    Postal code of the directory user address.

  • statestring

    State of the directory user address.

  • formattedstring

    Formatted address of the directory user.

  • custom_attributesobject

    Custom attributes of the directory user.

  • raw_attributesobject

    Raw attributes of the directory user as received from the Directory Provider (IdP).

scalekit.dir.user.create
Loading...

scalekit.dir.user.update

This webhook is triggered when a directory user is updated. Usually, directory user data is updated in any of the following scenarios:

  1. User Profile is updated in the Directory Provider (IdP) system.
  2. User is added to or removed from a group.
  3. If GBAC is enabled, User is assigned or removed from a role based on the group membership.
  • Event Data
  • idstring

    Unique ID of the Directory User.

  • organization_idstring

    Unique ID of the Organization to which this directory user belongs.

  • dp_idstring

    Unique ID of the User in the Directory Provider (IdP) system.

  • preferred_usernamestring

    Preferred username of the directory user.

  • emailstring

    Email of the directory user.

  • activeboolean

    Indicates if the directory user is active.

  • namestring

    Fully formatted name of the directory user.

  • rolesarray

    Array of roles assigned to the directory user.

    Child Attributes
  • rolestring

    Role of the directory user.

  • namestring

    Name of the directory user.

  • groupsarray

    Array of groups to which the directory user belongs.

    Child Attributes
  • idstring

    ID of the directory group.

  • namestring

    Name of the directory group.

  • given_namestring

    Given name of the directory user.

  • family_namestring

    Family name of the directory user.

  • nicknamestring

    Nickname of the directory user.

  • picturestring

    URL of the directory user's profile picture.

  • phone_numberstring

    Phone number of the directory user.

  • addressobject

    Address of the directory user.

    Child Attributes
  • postal_codestring

    Postal code of the directory user address.

  • statestring

    State of the directory user address.

  • formattedstring

    Formatted address of the directory user.

  • custom_attributesobject

    Custom attributes of the directory user.

  • raw_attributesobject

    Raw attributes of the directory user as received from the Directory Provider (IdP).

scalekit.dir.user.update
Loading...

scalekit.dir.user.delete

This webhook is triggered when a directory user is deleted.

  • Event Data
  • idstring

    Unique ID of the Directory User.

  • organization_idstring

    Unique ID of the Organization to which this directory user belongs.

  • dp_idstring

    Unique ID of the User in the Directory Provider (IdP) system.

  • emailstring

    Email of the directory user.

scalekit.dir.user.delete
Loading...

scalekit.dir.group.create

This webhook is triggered when a new directory group is created.

  • Event Data
  • directory_idstring

    Unique identifier for the directory.

  • display_namestring

    Display name of the directory group.

  • external_idnull

    External identifier for the group, null if not specified.

  • idstring

    Unique identifier for the directory group.

  • organization_idstring

    Identifier for the organization associated with the group.

  • raw_attributesobject

    Raw attributes of the directory group.

    Child Attributes
  • displayNamestring

    Display name of the group as received from the directory provider.

  • membersnull

    Members of the group, null if not specified or empty.

  • environment_idstring

    Identifier for the environment where the event occurred.

  • idstring

    Unique identifier for the event.

  • objectstring

    Type of object the event relates to.

  • occurred_atstring

    Timestamp when the event occurred.

  • organization_idstring

    Identifier for the organization associated with the event.

  • spec_versionstring

    Specification version of the event.

  • typestring

    Type of the event, indicating the action that occurred.

scalekit.dir.group.create
Loading...

scalekit.dir.group.update

This webhook is triggered when a directory group is updated.

  • Event Data
  • directory_idstring

    Unique identifier for the directory.

  • display_namestring

    Display name of the directory group.

  • external_idnull

    External identifier for the group, null if not specified.

  • idstring

    Unique identifier for the directory group.

  • organization_idstring

    Identifier for the organization associated with the group.

  • raw_attributesobject

    Raw attributes of the directory group.

    Child Attributes
  • displayNamestring

    Display name of the group as received from the directory provider.

  • membersarray

    Array of members in the group.

    Child Attributes
  • displaystring

    Display name or email of the group member.

  • valuestring

    Unique identifier for the group member.

  • environment_idstring

    Identifier for the environment where the event occurred.

  • idstring

    Unique identifier for the event.

  • objectstring

    Type of object the event relates to.

  • occurred_atstring

    Timestamp when the event occurred.

  • organization_idstring

    Identifier for the organization associated with the event.

  • spec_versionstring

    Specification version of the event.

  • typestring

    Type of the event, indicating the action that occurred.

scalekit.dir.group.update
Loading...

scalekit.dir.group.delete

This webhook is triggered when a directory group is deleted.

  • Event Data
  • directory_idstring

    Unique identifier for the directory.

  • display_namestring

    Display name of the directory group.

  • dp_idstring

    Unique identifier for the group in the directory provider system.

  • idstring

    Unique identifier for the directory group.

  • organization_idstring

    Identifier for the organization associated with the group.

  • raw_attributesobject

    Raw attributes of the directory group as received from the provider.

    Child Attributes
  • displayNamestring

    Display name of the group as received from the directory provider.

  • externalIdstring

    External identifier for the group in the directory provider system.

  • membersarray

    Array of members in the group.

    Child Attributes
  • valuestring

    Unique identifier for the group member.

  • environment_idstring

    Identifier for the environment where the event occurred.

  • idstring

    Unique identifier for the event.

  • objectstring

    Type of object the event relates to.

  • occurred_atstring

    Timestamp when the event occurred.

  • organization_idstring

    Identifier for the organization associated with the event.

  • spec_versionstring

    Specification version of the event.

  • typestring

    Type of the event, indicating the action that occurred.

scalekit.dir.group.delete
Loading...