API Reference

API Reference

Complete reference for all Scalekit API endpoints

Organizations APIs

• List organizations

  Retrieve a paginated list of organizations within your environment. The response includes a `page_token` that can be used to access subsequent pages of results.

  GET /api/v1/organizations Organizations
  • page_size: Maximum number of organizations to return per page. Must be between 10 and 100
  • page_token: Pagination token from the previous response. Use to retrieve the next page of organizations
  • external_id: Your application's unique identifier for this organization, used to link Scalekit with your system

• Create an organization

  Creates a new organization in your environment. Use this endpoint to add a new tenant that can be configured with various settings and metadata

  POST /api/v1/organizations Organizations
  • organization: Organization details

• Get organization details

  Retrieves organization details by Scalekit ID, including name, region, metadata, and settings

  GET /api/v1/organizations/{id} Organizations
  • id: Unique scalekit-generated identifier that uniquely references an organization

• Update organization details

  Updates an organization's display name, external ID, or metadata. Requires a valid organization identifier. Region code cannot be modified through this endpoint.

  PATCH /api/v1/organizations/{id} Organizations
  • id: Unique identifier of the organization to be updated
  • organization:

• Delete an organization

  Remove an existing organization from the environment using its unique identifier

  DELETE /api/v1/organizations/{id} Organizations
  • id: Unique scalekit-generated identifier that uniquely references an organization

• Generate admin portal link

  Creates a time-limited Admin Portal URL for IT administrators to configure and manage Single Sign-On (SSO) connections within their organization. Generated links expire after 7 days (168 hours).

  PUT /api/v1/organizations/{id}/portal_links Organizations
  • id: Organization ID
  • features: Features to enable in the admin portal link. To enable features, append them as URL parameters: - Single Sign-On: ?features=sso - Directory Sync: ?features=dir_sync - Both features: ?features=sso&features=dir_sync Example URL: https://scalekit.com/portal/lnk_123?features=sso - dir_sync: Enables directory synchronization configuration in the portal - sso: Enables Single Sign-On (SSO) configuration in the portal

• Toggle organization settings

  Updates configuration settings for an organization. Supports modifying SSO configuration, directory synchronization settings, and session parameters. Requires organization ID and the specific settings to update.

  PATCH /api/v1/organizations/{id}/settings Organizations
  • id: Unique identifier of the organization to update settings. Must begin with 'org_' prefix
  • settings:

API Auth APIs

• List organization API clients

  Retrieves a paginated list of API clients for a specific organization. Returns client details including metadata, scopes, and secret information (without exposing actual secret values).

  GET /api/v1/organizations/{organization_id}/clients API Auth
  • organization_id: Unique identifier of the organization whose clients to list. Must start with 'org_' prefix.
  • page_size: Maximum number of clients to return per page Maximum number of API clients to return per page. Must be between 10 and 100
  • page_token: Pagination token from the previous response Pagination token from the previous response. Use to retrieve the next page of organization clients

• Create organization API client

  Creates a new API client for an organization. Returns the client details and a plain secret (available only once).

  POST /api/v1/organizations/{organization_id}/clients API Auth
  • organization_id: Unique identifier of the organization
  • client:

• Get organization API client

  Retrieves details of a specific API client in an organization.

  GET /api/v1/organizations/{organization_id}/clients/{client_id} API Auth
  • organization_id: Unique identifier of the organization
  • client_id: Unique identifier of the API client

• Update organization API client

  Updates an existing organization API client. Only specified fields are modified.

  PATCH /api/v1/organizations/{organization_id}/clients/{client_id} API Auth
  • organization_id: Unique identifier of the organization
  • client_id: Unique identifier of the client
  • client:

• Delete organization API client

  Permanently deletes an API client from an organization. This operation cannot be undone and will revoke all access for the client. All associated secrets will also be invalidated. Use this endpoint to remove unused or compromised clients.

  DELETE /api/v1/organizations/{organization_id}/clients/{client_id} API Auth
  • organization_id: Unique identifier of the organization that owns the client. Must start with 'org_' prefix.
  • client_id: Unique identifier of the API client to permanently delete. Must start with 'm2morg_' prefix.

• Create organization API client secret

  Creates a new secret for an organization API client. Returns the plain secret (available only once).

  POST /api/v1/organizations/{organization_id}/clients/{client_id}/secrets API Auth
  • organization_id: Unique identifier of the organization
  • client_id: Unique identifier of the API client

• Delete organization API client secret

  Permanently deletes a secret from an organization API client. This operation cannot be undone.

  DELETE /api/v1/organizations/{organization_id}/clients/{client_id}/secrets/{secret_id} API Auth
  • organization_id: Unique identifier of the organization
  • client_id: Unique identifier of the API client
  • secret_id: Unique identifier of the client secret

Directory APIs

• List organization directories

  List organization directories

  GET /api/v1/organizations/{organization_id}/directories Directory
  • organization_id: Unique identifier of the organization

• Get directory details

  Retrieves detailed information about a specific directory within an organization

  GET /api/v1/organizations/{organization_id}/directories/{id} Directory
  • organization_id: Unique identifier of the organization
  • id: Unique identifier of the directory

• Disable a directory

  Stops synchronization of users and groups from a specified directory within an organization. This operation prevents further updates from the connected Directory provider

  PATCH /api/v1/organizations/{organization_id}/directories/{id}:disable Directory
  • organization_id: A unique identifier for the organization. The value must begin with 'org_' and be between 1 and 32 characters long
  • id: A unique identifier for a directory within the organization. The value must begin with 'dir_' and be between 1 and 32 characters long

• Enable a directory

  Activates a directory within an organization, allowing it to synchronize users and groups with the connected Directory provider

  PATCH /api/v1/organizations/{organization_id}/directories/{id}:enable Directory
  • organization_id: A unique identifier for the organization. The value must begin with 'org_' and be between 1 and 32 characters long
  • id: A unique identifier for a directory within the organization. The value must begin with 'dir_' and be between 1 and 32 characters long

• List directory groups

  Retrieves all groups from a specified directory. Use this endpoint to view group structures from your connected identity provider.

  GET /api/v1/organizations/{organization_id}/directories/{directory_id}/groups Directory
  • organization_id: Unique identifier of the organization
  • directory_id: Unique identifier of the directory
  • page_size: Number of groups to return per page. Maximum value is 30. If not specified, defaults to 10
  • page_token: Token for pagination. Use the value returned in the 'next_page_token' field of the previous response
  • updated_after: Filter groups updated after this timestamp. Use ISO 8601 format
  • include_detail: If true, includes full group details. If false or not specified, returns basic information only
  • include_external_groups: If true, returns group and its details from external provider (default: false)

• List directory users

  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.

  GET /api/v1/organizations/{organization_id}/directories/{directory_id}/users Directory
  • organization_id: Unique identifier of the organization
  • directory_id: Unique identifier of the directory within the organization
  • page_size: Number of users to return per page. Maximum value is 30. If not specified, defaults to 10
  • page_token: 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_detail: 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_id: Filter users by their membership in a specific directory group
  • updated_after: Filter users that were updated after the specified timestamp. Use ISO 8601 format

Users APIs

• List all users in environment

  Retrieves a paginated list of all users across your entire environment. Use this endpoint to view all users regardless of their organization memberships. This is useful for administrative purposes, user audits, or when you need to see all users in your Scalekit environment. Supports pagination for large user bases.

  GET /api/v1/users Users
  • page_size: Maximum number of organizations to return per page. Must be between 10 and 100
  • page_token: Pagination token from the previous response. Use to retrieve the next page of organizations

• Get user

  Retrieves all details for a user by system-generated user ID or external ID. The response includes organization memberships and user metadata.

  GET /api/v1/users/{id} Users
  • id: System-generated user ID
  • external_id: Your application's unique identifier for this organization, used to link Scalekit with your system.

• Update user information

  Modifies user account information including profile details, metadata, and external ID. Use this endpoint to update a user's personal information, contact details, or custom metadata. You can update the user's profile, phone number, and metadata fields. Note that fields like user ID, email address, environment ID, and creation time cannot be modified.

  PATCH /api/v1/users/{id} Users
  • id: System-generated user ID. Must start with 'usr_' and be 19-25 characters long.
  • user:
  • external_id: Your application's unique identifier for this organization, used to link Scalekit with your system.

• Delete user permanently

  Permanently removes a user from your environment and deletes all associated data. Use this endpoint when you need to completely remove a user account. This action deletes the user's profile, memberships, and all related data across all organizations. This operation cannot be undone, so use with caution.

  DELETE /api/v1/users/{id} Users
  • id: System-generated user ID. Must start with 'usr_' (19-25 characters)
  • external_id: External system identifier from connected directories. Must match existing records

• List organization users

  Retrieves a paginated list of all users who are members of the specified organization. Use this endpoint to view all users with access to a particular organization, including their roles, metadata, and membership details. Supports pagination for large user lists.

  GET /api/v1/organizations/{organization_id}/users Users
  • organization_id: Unique identifier of the organization for which to list users. Must start with 'org_' and be 1-32 characters long.
  • page_size: Maximum number of users to return in a single response. Valid range: 1-100. Server may return fewer users than specified.
  • page_token: Pagination token from a previous ListUserResponse. Used to retrieve the next page of results. Leave empty for the first request.

• Create new user in organization

  Creates a new user account and immediately adds them to the specified organization. Use this endpoint when you want to create a user and grant them access to an organization in a single operation. You can provide user profile information, assign roles, and configure membership metadata. The user receives an activation email unless this feature is disabled in the organization settings.

  POST /api/v1/organizations/{organization_id}/users Users
  • organization_id:
  • user:
  • send_invitation_email: If true, sends an activation email to the user. Defaults to true.

• Add existing user to organization

  Adds an existing user to an organization and assigns them specific roles and permissions. Use this endpoint when you want to grant an existing user access to a particular organization. You can specify roles, metadata, and other membership details during the invitation process.

  POST /api/v1/memberships/organizations/{organization_id}/users/{id} Users
  • organization_id: Unique identifier of the target organization. Must start with 'org_' and be 1-32 characters long.
  • id: System-generated user ID. Must start with 'usr_' (19-25 characters)
  • membership:
  • external_id: External system identifier from connected directories. Must be unique across the system
  • send_invitation_email: If true, sends an activation email to the user. Defaults to true.

• Delete organization membership for user

  Removes a user from an organization by user ID or external ID. If the user has no memberships left and cascade is true, the user is also deleted. This action is irreversible and may also remove related group memberships.

  DELETE /api/v1/memberships/organizations/{organization_id}/users/{id} Users
  • organization_id: Unique organization identifier. Must start with 'org_' and be 1-32 characters long
  • id: System-generated user ID. Must start with 'usr_' (19-25 characters)
  • external_id: External system identifier from connected directories. Must match existing records

Connections APIs

• List connections

  Retrieves a list of connections in the environment

  GET /api/v1/connections Connections
  • organization_id: Filter connections by organization identifier
  • domain: Filter connections by email domain associated with the organization
  • include: Filter connections by status. Use 'all' to include all connections regardless of status. Default behavior shows only active (completed and enabled) connections

• Get connection details

  Retrieves the complete configuration and status details for a specific connection by its ID within an organization. Returns all connection properties including provider settings, protocols, and current status.

  GET /api/v1/organizations/{organization_id}/connections/{id} Connections
  • organization_id: Organization identifier (required). Specifies which organization owns the connection you want to retrieve.
  • id: Connection identifier (required). Specifies which specific connection to retrieve from the organization.

• Disable organization connection

  Deactivate an existing connection for the specified organization. When disabled, users cannot authenticate using this connection. This endpoint changes the connection state from enabled to disabled without modifying other configuration settings

  PATCH /api/v1/organizations/{organization_id}/connections/{id}:disable Connections
  • organization_id: Unique identifier of the organization associated with the connection
  • id: Unique identifier for the connection to be toggled

• Enable organization connection

  Activate an existing connection for the specified organization. When enabled, users can authenticate using this connection. This endpoint changes the connection state from disabled to enabled without modifying other configuration settings

  PATCH /api/v1/organizations/{organization_id}/connections/{id}:enable Connections
  • organization_id: Unique identifier of the organization associated with the connection
  • id: Unique identifier for the connection to be toggled

Passwordless Auth APIs

• Send passwordless email

  Send a verification email containing either a verification code (OTP), magic link, or both to a user's email address

  POST /api/v1/passwordless/email/send Passwordless Auth
  • body:

• Resend passwordless email

  Resend a verification email if the user didn't receive it or if the previous code/link has expired

  POST /api/v1/passwordless/email/resend Passwordless Auth
  • body:

• Verify passwordless email

  Verify a user's identity using either a verification code or magic link token

  POST /api/v1/passwordless/email/verify Passwordless Auth
  • body: