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

• 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

• Get organization details

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

  GET /api/v1/organizations/{id} Organizations

• 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

• Delete an organization

  Remove an existing organization from the environment using its unique identifier

  DELETE /api/v1/organizations/{id} Organizations

• 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

• 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

API Auth APIs

• 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

• 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

• 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

• 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

• 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

• 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

Directory APIs

• List organization directories

  List organization directories

  GET /api/v1/organizations/{organization_id}/directories Directory

• Get directory details

  Retrieves detailed information about a specific directory within an organization

  GET /api/v1/organizations/{organization_id}/directories/{id} 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

• 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

• 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

• 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

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

• 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

• 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

• 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

• 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

• 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. If user already exists, user will be added to the organization.

  POST /api/v1/organizations/{organization_id}/users Users

• 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

• Update organization membership for user

  Updates a user's membership details within an organization by user ID or external ID. You can update roles and membership metadata.

  PATCH /api/v1/memberships/organizations/{organization_id}/users/{id} Users

• 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

Connections APIs

• List organization connections

  Retrieves a list of connections for all the organizations

  GET /api/v1/organizations/-/connections 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

• 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

• 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

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

• 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

• 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