API Reference
API Reference
Section titled “API Reference”Complete reference for all Scalekit API endpoints
Organizations APIs
Section titled “Organizations APIs ”-
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
-
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
-
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
-
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:
-
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
-
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
-
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
Section titled “API Auth APIs ”-
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
-
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:
-
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
-
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:
-
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.
-
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
-
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
Section titled “Directory APIs ”-
List organization directories
GET/api/v1/organizations/{organization_id}/directories
Directory- organization_id: Unique identifier of the organization
-
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
-
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
-
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
-
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)
-
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
Section titled “Users APIs ”-
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
-
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.
-
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.
-
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
-
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.
-
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.
-
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.
-
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
-
Resends an invitation email to a user who has a pending or expired invitation in the specified organization. If the invitation has expired, a new invitation will be automatically created and sent. If the invitation is still valid, a reminder email will be sent instead. Use this endpoint when a user hasn't responded to their initial invitation and you need to send them a reminder or when the original invitation has expired. The invitation email includes a secure magic link that allows the user to complete their account setup and join the organization. Each resend operation increments the resent counter.
PATCH/api/v1/invites/organizations/{organization_id}/users/{id}/resend
Users- organization_id: Unique identifier of the organization containing the pending invitation. Must start with 'org_' and be 1-32 characters long.
- id: System-generated user ID of the user who has a pending invitation. Must start with 'usr_' and be 19-25 characters long.
- body:
Roles APIs
Section titled “Roles APIs ”-
Retrieves a comprehensive list of all roles available within the environment. Use this endpoint to view all role definitions, including system default roles and custom roles. You can optionally include permission details for each role to understand their capabilities. This is useful for role management, auditing, or understanding the available access levels in your system.
GET/api/v1/roles
Roles- include: Include additional data in the response. Valid values: 'permissions' (direct permissions only), 'permissions:all' (includes inherited permissions from role hierarchy)
-
Creates a new role within the environment with specified permissions and metadata. Use this endpoint to define custom roles that can be assigned to users or groups. You can create hierarchical roles by extending existing roles, assign specific permissions, and configure display information. Roles are the foundation of your access control system and determine what actions users can perform.
POST/api/v1/roles
Roles- role:
-
Retrieves complete information for a specific role including metadata and inheritance details (base role and dependent role count). Use this endpoint to audit role configuration and understand the role's place in the hierarchy. To view the role's permissions, use the ListRolePermissions endpoint.
GET/api/v1/roles/{role_name}
Roles- role_name: Unique name identifier of the role to retrieve. Must be alphanumeric with underscores, 1-64 characters.
- include: Include additional data in the response. Valid values: 'permissions' (direct permissions only), 'permissions:all' (includes inherited permissions from role hierarchy)
-
Modifies an existing role's properties including display name, description, permissions, and inheritance. Use this endpoint to update role metadata, change permission assignments, or modify role hierarchy. Only the fields you specify will be updated, leaving other properties unchanged. When updating permissions, the new list replaces all existing permissions for the role.
PUT/api/v1/roles/{role_name}
Roles- role_name: Unique name identifier of the role to update. Must be alphanumeric with underscores, 1-64 characters.
- role:
-
Permanently removes a role from the environment and reassigns users who had that role to a different role. Use this endpoint when you need to clean up unused roles or restructure your access control system. The role cannot be deleted if it has dependent roles (roles that extend it) unless you specify a replacement role. If users are assigned to the role being deleted, you must provide a reassign_role_name to move those users to a different role before deletion can proceed. This action cannot be undone, so ensure no critical users depend on the role before deletion.
DELETE/api/v1/roles/{role_name}
Roles- role_name: Unique name identifier of the role to delete. Must be alphanumeric with underscores, 1-64 characters.
- reassign_role_id: Role name to reassign users to when deleting this role
- reassign_role_name: Role name to reassign users to when deleting this role
-
Removes the base role inheritance relationship for a specified role, effectively eliminating all inherited permissions from the base role. Use this endpoint when you want to break the hierarchical relationship between roles and remove inherited permissions. The role will retain only its directly assigned permissions after this operation. This action cannot be undone, so ensure the role has sufficient direct permissions before removing inheritance. Returns no content on successful removal of the base relationship.
DELETE/api/v1/roles/{role_name}/base
Roles- role_name: Unique name identifier of the role whose base inheritance relationship should be removed. Must be alphanumeric with underscores, 1-64 characters.
-
Retrieves all roles that directly extend the specified base role through inheritance. Use this endpoint to understand the role hierarchy and identify which roles inherit permissions from a particular base role. Provide the base role name as a path parameter, and the response will include all dependent roles with their metadata and permission information. This operation is useful for auditing role inheritance relationships, understanding the impact of changes to base roles, or managing role hierarchies effectively. Returns a list of dependent role objects including their names, display names, descriptions, and permission details.
GET/api/v1/roles/{role_name}/dependents
Roles- role_name: Name of the base role
-
Retrieves all permissions directly assigned to the specified role, excluding permissions inherited from base roles. Use this endpoint to view the explicit permission assignments for a role, which is useful for understanding direct role capabilities, auditing permission assignments, or managing role-permission relationships. Provide the role name as a path parameter, and the response will include only the permissions that are directly assigned to that role. This operation does not include inherited permissions from role hierarchies - use ListEffectiveRolePermissions to see the complete set of permissions including inheritance. Returns a list of permission objects with their names, descriptions, and assignment metadata.
GET/api/v1/roles/{role_name}/permissions
Roles- role_name: Name of the role
-
Adds one or more permissions to the specified role while preserving existing permission assignments. Use this endpoint to grant additional capabilities to a role without affecting its current permission set. Provide the role name as a path parameter and a list of permission names in the request body. The system will validate that all specified permissions exist in the environment and add them to the role. Existing permission assignments remain unchanged, making this operation safe for incremental permission management. This is useful for gradually expanding role capabilities or adding new permissions as your system evolves. Returns the updated list of all permissions now assigned to the role.
POST/api/v1/roles/{role_name}/permissions
Roles- role_name: Name of the role
- body:
-
Retrieves the complete set of effective permissions for a role, including both directly assigned permissions and permissions inherited from base roles through the role hierarchy. Use this endpoint to understand the full scope of capabilities available to users assigned to a specific role. Provide the role name as a path parameter, and the response will include all permissions that apply to the role, accounting for inheritance relationships. This operation is essential for auditing role capabilities, understanding permission inheritance, or verifying the complete access scope before role assignment. Returns a comprehensive list of permission names representing the full set of effective permissions for the specified role.
GET/api/v1/roles/{role_name}/permissions:all
Roles- role_name: Name of the role
-
Retrieves the total number of users currently assigned to the specified role within the environment. Use this endpoint to monitor role usage, enforce user limits, or understand the scope of role assignments. Provide the role's unique name as a path parameter, and the response will include the current user count for that role. This operation is read-only and does not modify any data or user assignments. The count reflects all users who have the role either directly assigned or inherited through organization membership. This information is useful for capacity planning, security auditing, or understanding the impact of role changes across your user base.
GET/api/v1/roles/{role_name}/users:count
Roles- role_name: Unique name of the role
-
Removes a specific permission from the specified role, revoking that capability from all users assigned to the role. Use this endpoint to restrict role capabilities or remove unnecessary permissions. Provide both the role name and permission name as path parameters. This operation only affects the direct permission assignment and does not impact permissions inherited from base roles. If the permission is inherited through role hierarchy, you may need to modify the base role instead. This is useful for fine-tuning role permissions, implementing least-privilege access controls, or removing deprecated permissions. Returns no content on successful removal.
DELETE/api/v1/roles/{role_name}/permissions/{permission_name}
Roles- role_name: Name of the role
- permission_name: Name of the permission to remove
Permissions APIs
Section titled “Permissions APIs ”-
Retrieves a comprehensive, paginated list of all permissions available within the environment. Use this endpoint to view all permission definitions for auditing, role management, or understanding the complete set of available access controls. The response includes pagination tokens to navigate through large sets of permissions efficiently. Each permission object contains the permission name, description, creation time, and last update time. This operation is useful for building permission selection interfaces, auditing permission usage, or understanding the scope of available access controls in your RBAC system.
GET/api/v1/permissions
Permissions- page_token: Page token to retrieve next page of results
- page_size: Number of permissions to return per page (max 100)
-
Creates a new permission that represents a specific action users can perform within the environment. Use this endpoint to define granular access controls for your RBAC system. You can provide a unique permission name following the format 'action:resource' (for example, 'read:documents', 'write:users') and an optional description explaining the permission's purpose. The permission name must be unique across the environment and follows alphanumeric naming conventions with colons and underscores. Returns the created permission object including system-generated ID and timestamps.
POST/api/v1/permissions
Permissions- permission:
-
Retrieves complete information for a specific permission by its unique name identifier. Use this endpoint to view permission details including description, creation time, and last update time. Provide the permission name in the path parameter following the format 'action:resource' (for example, 'read:documents'). This operation is useful for auditing permission definitions, understanding permission purposes, or verifying permission existence before assignment. Returns the complete permission object with all metadata and system-generated timestamps.
GET/api/v1/permissions/{permission_name}
Permissions- permission_name: Name of the permission
-
Modifies an existing permission's attributes including description and metadata. Use this endpoint to update permission descriptions or clarify permission purposes after creation. The permission is identified by its unique name in the path parameter, and only the fields you specify in the request body will be updated. Note that the permission name itself cannot be changed as it serves as the immutable identifier. This operation is useful for maintaining clear documentation of permission purposes or updating descriptions to reflect changes in system functionality. Returns the updated permission object with modified timestamps.
PUT/api/v1/permissions/{permission_name}
Permissions- permission_name: Name of the permission
- permission:
-
Permanently removes a permission from the environment using its unique name identifier. Use this endpoint when you need to clean up unused permissions or remove access controls that are no longer relevant. The permission is identified by its name in the path parameter following the format 'action:resource'. This operation cannot be undone, so ensure no active roles depend on the permission before deletion. If the permission is currently assigned to any roles, you may need to remove those assignments first or update the roles to use alternative permissions. Returns no content on successful deletion.
DELETE/api/v1/permissions/{permission_name}
Permissions- permission_name: Name of the permission
Connections APIs
Section titled “Connections APIs ”-
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
-
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.
-
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
-
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
Section titled “Passwordless Auth APIs ”-
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 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 a user's identity using either a verification code or magic link token
POST/api/v1/passwordless/email/verify
Passwordless Auth- body: