Skip to content
Scalekit Docs
Talk to an Engineer Start implementing

Python

Complete API reference for the Scalekit Python SDK

ScalekitClient

client.get_authorization_url(redirect_uri, options?) -> str

📝 Description

Utility method to generate the OAuth 2.0 authorization URL to initiate the SSO authentication flow.

This method doesn’t make any network calls but instead generates a fully formed Authorization URL as a string that you can redirect your users to initiate authentication.

🔌 Usage

from scalekit import ScalekitClient, AuthorizationUrlOptions


# Initiate Enterprise SSO authentication for a given org_id
options = AuthorizationUrlOptions()
options.state = 'random-state-value'
options.organization_id = 'org_123456'


auth_url = scalekit_client.get_authorization_url(
    'https://yourapp.com/auth/callback',
    options
)
# Redirect user to auth_url

⚙️ Parameters

redirect_uri: str - The URL where users will be redirected after authentication. Must match one of the redirect URIs configured in your Scalekit dashboard.

options: AuthorizationUrlOptions - Optional configuration for the authorization request

  • scopes: Optional[list[str]] - OAuth scopes to request (default: [‘openid’, ‘profile’, ‘email’])
  • state: Optional[str] - Opaque value to maintain state between request and callback
  • nonce: Optional[str] - String value used to associate a client session with an ID Token
  • login_hint: Optional[str] - Hint about the login identifier the user might use
  • domain_hint: Optional[str] - Domain hint to identify which organization’s IdP to use
  • connection_id: Optional[str] - Specific SSO connection ID to use for authentication
  • organization_id: Optional[str] - Organization ID to authenticate against
  • provider: Optional[str] - Social login provider (e.g., ‘google’, ‘github’, ‘microsoft’)
  • prompt: Optional[str] - Controls authentication behavior (e.g., ‘login’, ‘consent’, ‘create’)
client.authenticate_with_code(code, redirect_uri, options?) -> dict

📝 Description

Exchanges an authorization code for access tokens and user information.

This method completes the OAuth 2.0 authorization code flow by exchanging the code received in the callback for access tokens, ID tokens, and user profile information. Call this method in your redirect URI handler after receiving the authorization code.

🔌 Usage

from scalekit import ScalekitClient


@app.get('/auth/callback')
async def auth_callback(request):
    code = request.query_params.get('code')


    result = scalekit_client.authenticate_with_code(
        code,
        'https://yourapp.com/auth/callback'
    )


    request.session['access_token'] = result['access_token']
    request.session['user'] = result['user']


    return RedirectResponse('/dashboard')

⚙️ Parameters

code: str - The authorization code received in the callback URL after user authentication

redirect_uri: str - The same redirect URI used in get_authorization_url(). Must match exactly.

options: CodeAuthenticationOptions - Optional authentication configuration

  • code_verifier: Optional[str] - PKCE code verifier to validate the code challenge (required if PKCE was used)
client.get_idp_initiated_login_claims(idp_initiated_login_token, options?) -> IdpInitiatedLoginClaims

📝 Description

Extracts and validates claims from an IdP-initiated login token.

Use this method when handling IdP-initiated SSO flows, where the authentication is initiated from the identity provider’s portal rather than your application. This validates the token and returns the necessary information to initiate a new SP Initiated SSO workflow.

🔌 Usage

@app.get('/auth/callback')
async def auth_callback(request):
    idp_initiated_login = request.query_params.get('idp_initiated_login')


    if idp_initiated_login:
        claims = scalekit_client.get_idp_initiated_login_claims(idp_initiated_login)


        options = AuthorizationUrlOptions()
        options.connection_id = claims['connection_id']
        options.organization_id = claims['organization_id']
        options.login_hint = claims.get('login_hint')
        if claims.get('relay_state'):
            options.state = claims['relay_state']


        auth_url = scalekit_client.get_authorization_url(
            'https://yourapp.com/auth/callback',
            options
        )


        return RedirectResponse(auth_url)

⚙️ Parameters

idp_initiated_login_token: str - The token received in the ‘idp_initiated_login’ query parameter

options: TokenValidationOptions - Optional token validation configuration

client.validate_access_token(token, options?) -> bool

📝 Description

Validates the access token and returns a boolean result.

🔌 Usage

is_valid = scalekit_client.validate_access_token(token)
if is_valid:
    # Token is valid, proceed with request
    pass

⚙️ Parameters

token: str - The token to be validated

options: TokenValidationOptions - Optional validation options for issuer, audience, and scopes

client.get_logout_url(options?) -> str

📝 Description

Returns the logout URL that can be used to log out the user.

🔌 Usage

options = LogoutUrlOptions()
options.post_logout_redirect_uri = 'https://example.com'
options.state = 'some-state'


logout_url = scalekit_client.get_logout_url(options)

⚙️ Parameters

options: LogoutUrlOptions - Logout URL options

  • id_token_hint: Optional[str] - The ID Token previously issued to the client
  • post_logout_redirect_uri: Optional[str] - URL to redirect after logout
  • state: Optional[str] - Opaque value to maintain state between request and callback
client.verify_webhook_payload(secret, headers, payload) -> bool

📝 Description

Verifies the webhook payload signature using the provided secret.

🔌 Usage

@app.post('/webhooks')
async def webhook_handler(request):
    payload = await request.body()
    headers = dict(request.headers)


    is_valid = scalekit_client.verify_webhook_payload(
        'your_webhook_secret',
        headers,
        payload
    )


    if is_valid:
        # Process webhook
        pass

⚙️ Parameters

secret: str - Secret for webhook verification

headers: Dict[str, str] - Webhook request headers

payload: str | bytes - Webhook payload in str or bytes

client.refresh_access_token(refresh_token) -> dict

📝 Description

Refreshes an access token using a refresh token.

🔌 Usage

result = scalekit_client.refresh_access_token(refresh_token)
new_access_token = result['access_token']
new_refresh_token = result['refresh_token']

⚙️ Parameters

refresh_token: str - Refresh token to get new access token

Organization

client.organization.list_organizations(page_size, page_token?) -> ListOrganizationsResponse

📝 Description

Lists all organizations with pagination support.

🔌 Usage

response = scalekit_client.organization.list_organizations(
    page_size=50,
    page_token='next_page_token'
)


for org in response[0].organizations:
    print(f"Organization: {org.display_name}")

⚙️ Parameters

page_size: int - Page size for organization list fetch

page_token: Optional[str] - Page token for pagination

client.organization.create_organization(organization) -> CreateOrganizationResponse

📝 Description

Creates a new organization with the provided details.

🔌 Usage

from scalekit.v1.organizations.organizations_pb2 import CreateOrganization


org = CreateOrganization()
org.display_name = "Acme Corp"
org.external_id = "acme_123"


response = scalekit_client.organization.create_organization(org)
print(f"Created organization: {response[0].organization.id}")

⚙️ Parameters

organization: CreateOrganization - Organization object with details for creation

client.organization.get_organization(organization_id) -> GetOrganizationResponse

📝 Description

Retrieves organization details by organization ID.

🔌 Usage

response = scalekit_client.organization.get_organization('org_123456')
organization = response[0].organization
print(f"Organization: {organization.display_name}")

⚙️ Parameters

organization_id: str - Organization ID

client.organization.get_organization_by_external_id(external_id) -> GetOrganizationResponse

📝 Description

Retrieves organization details by external ID.

🔌 Usage

response = scalekit_client.organization.get_organization_by_external_id('acme_123')
organization = response[0].organization

⚙️ Parameters

external_id: str - External ID to fetch organization details

client.organization.update_organization(organization_id, organization) -> UpdateOrganizationResponse

📝 Description

Updates an existing organization with new information.

🔌 Usage

from scalekit.v1.organizations.organizations_pb2 import UpdateOrganization


org = UpdateOrganization()
org.display_name = "Acme Corporation"


response = scalekit_client.organization.update_organization('org_123456', org)

⚙️ Parameters

organization_id: str - Organization ID to update

organization: UpdateOrganization - Parameters for update organization operation

client.organization.delete_organization(organization_id)

📝 Description

Deletes an organization by organization ID.

🔌 Usage

scalekit_client.organization.delete_organization('org_123456')

⚙️ Parameters

organization_id: str - Organization ID

client.organization.generate_portal_link(organization_id, features?) -> str

📝 Description

Generates a customer portal link for the organization.

🔌 Usage

portal_link = scalekit_client.organization.generate_portal_link('org_123456')
print(f"Portal Link: {portal_link}")

⚙️ Parameters

organization_id: str - Organization ID to fetch portal link for

features: Optional[list[Feature]] - Feature list to generate portal link for

Connection

client.connection.list_connections(organization_id, include?) -> ListConnectionsResponse

📝 Description

Lists all SSO connections for an organization.

🔌 Usage

response = scalekit_client.connection.list_connections(
    'org_123456',
    include='all'
)


for conn in response[0].connections:
    print(f"Connection: {conn.id}")

⚙️ Parameters

organization_id: str - Organization ID to get connections

include: Optional[str] - Return active connections or all (e.g., ‘all’)

client.connection.list_connections_by_domain(domain, include?) -> ListConnectionsResponse

📝 Description

Lists all SSO connections for a domain.

🔌 Usage

response = scalekit_client.connection.list_connections_by_domain(
    'acme.com',
    include='all'
)

⚙️ Parameters

domain: str - Domain to get connections

include: Optional[str] - Return active connections or all

client.connection.get_connection(organization_id, conn_id) -> GetConnectionResponse

📝 Description

Retrieves a specific SSO connection by ID.

🔌 Usage

response = scalekit_client.connection.get_connection(
    'org_123456',
    'conn_123456'
)
connection = response[0].connection

⚙️ Parameters

organization_id: str - Organization ID

conn_id: str - Connection ID

client.connection.create_connection(organization_id, connection) -> CreateConnectionResponse

📝 Description

Creates a new SSO connection for an organization.

🔌 Usage

from scalekit.v1.connections.connections_pb2 import CreateConnection


connection = CreateConnection()
connection.type = "SAML"


response = scalekit_client.connection.create_connection(
    'org_123456',
    connection
)

⚙️ Parameters

organization_id: str - Organization ID

connection: CreateConnection - Connection object with expected values

client.connection.enable_connection(organization_id, conn_id) -> ToggleConnectionResponse

📝 Description

Enables an SSO connection for an organization.

🔌 Usage

scalekit_client.connection.enable_connection('org_123456', 'conn_123456')

⚙️ Parameters

organization_id: str - Organization ID

conn_id: str - Connection ID

client.connection.disable_connection(organization_id, conn_id) -> ToggleConnectionResponse

📝 Description

Disables an SSO connection for an organization.

🔌 Usage

scalekit_client.connection.disable_connection('org_123456', 'conn_123456')

⚙️ Parameters

organization_id: str - Organization ID

conn_id: str - Connection ID

client.connection.delete_connection(organization_id, connection_id)

📝 Description

Deletes an SSO connection from an organization.

🔌 Usage

scalekit_client.connection.delete_connection('org_123456', 'conn_123456')

⚙️ Parameters

organization_id: str - Organization ID

connection_id: str - Connection ID to be deleted

Domain

client.domain.create_domain(organization_id, domain_name, domain_type?) -> CreateDomainResponse

📝 Description

Creates a new domain for an organization.

🔌 Usage

response = scalekit_client.domain.create_domain(
    'org_123456',
    'acme.com',
    domain_type='ORGANIZATION_DOMAIN'
)

⚙️ Parameters

organization_id: str - Organization ID to create domain for

domain_name: str - Domain name for new creation

domain_type: Optional[str | DomainType] - Type of domain (“ALLOWED_EMAIL_DOMAIN”, “ORGANIZATION_DOMAIN”, or “UNSPECIFIED”)

client.domain.list_domains(organization_id, domain_type?) -> ListDomainResponse

📝 Description

Lists all domains for an organization.

🔌 Usage

response = scalekit_client.domain.list_domains(
    'org_123456',
    domain_type='ORGANIZATION_DOMAIN'
)


for domain in response[0].domains:
    print(f"Domain: {domain.domain}")

⚙️ Parameters

organization_id: str - Organization ID to list domains for

domain_type: Optional[str | DomainType] - Type of domain to filter by

client.domain.get_domain(organization_id, domain_id) -> GetDomainResponse

📝 Description

Retrieves a specific domain by ID.

🔌 Usage

response = scalekit_client.domain.get_domain('org_123456', 'domain_123456')
domain = response[0].domain

⚙️ Parameters

organization_id: str - Organization ID

domain_id: str - Domain ID

client.domain.delete_domain(organization_id, domain_id)

📝 Description

Deletes a domain from an organization.

🔌 Usage

scalekit_client.domain.delete_domain('org_123456', 'domain_123456')

⚙️ Parameters

organization_id: str - Organization ID

domain_id: str - Domain ID to delete

Directory

client.directory.list_directories(organization_id) -> ListDirectoriesResponse

📝 Description

Lists all directories for an organization.

🔌 Usage

response = scalekit_client.directory.list_directories('org_123456')


for directory in response[0].directories:
    print(f"Directory: {directory.id}")

⚙️ Parameters

organization_id: str - Organization ID to fetch directory list

client.directory.get_directory(organization_id, directory_id) -> GetDirectoryResponse

📝 Description

Retrieves a specific directory by ID.

🔌 Usage

response = scalekit_client.directory.get_directory(
    'org_123456',
    'directory_123456'
)
directory = response[0].directory

⚙️ Parameters

organization_id: str - Organization ID

directory_id: str - Directory ID

client.directory.create_directory(organization_id, directory) -> CreateDirectoryResponse

📝 Description

Creates a new directory for an organization.

🔌 Usage

from scalekit.v1.directories.directories_pb2 import CreateDirectory


directory = CreateDirectory()
directory.provider = "azure"


response = scalekit_client.directory.create_directory(
    'org_123456',
    directory
)

⚙️ Parameters

organization_id: str - Organization ID to create directory for

directory: CreateDirectory - Directory object with expected values for creation

client.directory.list_directory_users(organization_id, directory_id, page_size?, page_token?, include_detail?, updated_after?) -> tuple[ListDirUsersResponse, Any]

📝 Description

Lists all users in a directory with pagination support.

🔌 Usage

response = scalekit_client.directory.list_directory_users(
    'org_123456',
    'directory_123456',
    page_size=50
)


for user in response[0].users:
    print(f"User: {user.email}")

⚙️ Parameters

organization_id: str - Organization ID

directory_id: str - Directory ID

page_size: Optional[int] - Page size for pagination

page_token: Optional[str] - Page token for pagination

include_detail: Optional[bool] - Include detailed data

updated_after: Optional[str] - Get updated after detail

client.directory.list_directory_groups(organization_id, directory_id, page_size?, page_token?, include_detail?, updated_after?) -> tuple[ListDirGroupsResponse, Any]

📝 Description

Lists all groups in a directory with pagination support.

🔌 Usage

response = scalekit_client.directory.list_directory_groups(
    'org_123456',
    'directory_123456',
    page_size=50
)


for group in response[0].groups:
    print(f"Group: {group.display_name}")

⚙️ Parameters

organization_id: str - Organization ID

directory_id: str - Directory ID

page_size: Optional[int] - Page size for pagination

page_token: Optional[str] - Page token for pagination

include_detail: Optional[bool] - Include detailed data

updated_after: Optional[str] - Get updated after detail

client.directory.enable_directory(organization_id, directory_id) -> ToggleDirectoryResponse

📝 Description

Enables a directory for an organization.

🔌 Usage

scalekit_client.directory.enable_directory('org_123456', 'directory_123456')

⚙️ Parameters

organization_id: str - Organization ID

directory_id: str - Directory ID

client.directory.disable_directory(organization_id, directory_id) -> ToggleDirectoryResponse

📝 Description

Disables a directory for an organization.

🔌 Usage

scalekit_client.directory.disable_directory('org_123456', 'directory_123456')

⚙️ Parameters

organization_id: str - Organization ID

directory_id: str - Directory ID

client.directory.delete_directory(organization_id, directory_id)

📝 Description

Deletes a directory from an organization.

🔌 Usage

scalekit_client.directory.delete_directory('org_123456', 'directory_123456')

⚙️ Parameters

organization_id: str - Organization ID

directory_id: str - Directory ID for directory to be deleted

User

client.users.list_users(page_size?, page_token?) -> ListUsersResponse

📝 Description

Lists all users in the environment with pagination support.

🔌 Usage

response = scalekit_client.users.list_users(
    page_size=50,
    page_token='next_page_token'
)


for user in response[0].users:
    print(f"User: {user.email}")

⚙️ Parameters

page_size: Optional[int] - Page size for pagination

page_token: Optional[str] - Page token for pagination

client.users.list_organization_users(organization_id, page_size?, page_token?) -> ListOrganizationUsersResponse

📝 Description

Lists all users in a specific organization with pagination support.

🔌 Usage

response = scalekit_client.users.list_organization_users(
    'org_123456',
    page_size=50
)


for user in response[0].users:
    print(f"User: {user.email}")

⚙️ Parameters

organization_id: str - Organization ID to list users for

page_size: Optional[int] - Page size for pagination

page_token: Optional[str] - Page token for pagination

client.users.get_user(user_id) -> GetUserResponse

📝 Description

Retrieves user details by user ID.

🔌 Usage

response = scalekit_client.users.get_user('usr_123456')
user = response[0].user
print(f"User: {user.email}")

⚙️ Parameters

user_id: str - User ID to get user details

client.users.get_user_by_external_id(external_id) -> GetUserResponse

📝 Description

Retrieves user details by external ID.

🔌 Usage

response = scalekit_client.users.get_user_by_external_id('external_123')
user = response[0].user

⚙️ Parameters

external_id: str - External ID to get user details

client.users.create_user_and_membership(organization_id, user, send_invitation_email?) -> CreateUserAndMembershipResponse

📝 Description

Creates a new user and adds them to an organization.

🔌 Usage

from scalekit.v1.users.users_pb2 import CreateUser


user = CreateUser()
user.email = "john.doe@example.com"
user.given_name = "John"
user.family_name = "Doe"


response = scalekit_client.users.create_user_and_membership(
    'org_123456',
    user,
    send_invitation_email=True
)

⚙️ Parameters

organization_id: str - Organization ID to create user for

user: CreateUser - User object with expected values for user creation

send_invitation_email: bool - Whether to send invitation email to the user (default: True)

client.users.update_user(user_id, user) -> UpdateUserResponse

📝 Description

Updates an existing user by user ID.

🔌 Usage

from scalekit.v1.users.users_pb2 import UpdateUser


user = UpdateUser()
user.given_name = "John"


response = scalekit_client.users.update_user('usr_123456', user)

⚙️ Parameters

user_id: str - User ID to update

user: UpdateUser - User object with expected values for user update

client.users.delete_user(user_id)

📝 Description

Deletes a user by user ID.

🔌 Usage

scalekit_client.users.delete_user('usr_123456')

⚙️ Parameters

user_id: str - User ID to be deleted

client.users.create_membership(organization_id, user_id, membership, send_invitation_email?) -> CreateMembershipResponse

📝 Description

Creates a membership for a user in an organization.

🔌 Usage

from scalekit.v1.users.users_pb2 import CreateMembership


membership = CreateMembership()


response = scalekit_client.users.create_membership(
    'org_123456',
    'usr_123456',
    membership,
    send_invitation_email=True
)

⚙️ Parameters

organization_id: str - Organization ID

user_id: str - User ID

membership: CreateMembership - Membership object

send_invitation_email: bool - Whether to send invitation email (default: True)

client.users.update_membership(organization_id, user_id, membership) -> UpdateMembershipResponse

📝 Description

Updates a membership for a user in an organization.

🔌 Usage

from scalekit.v1.users.users_pb2 import UpdateMembership


membership = UpdateMembership()


response = scalekit_client.users.update_membership(
    'org_123456',
    'usr_123456',
    membership
)

⚙️ Parameters

organization_id: str - Organization ID

user_id: str - User ID

membership: UpdateMembership - Membership object

client.users.delete_membership(organization_id, user_id)

📝 Description

Deletes a membership for a user in an organization.

🔌 Usage

scalekit_client.users.delete_membership('org_123456', 'usr_123456')

⚙️ Parameters

organization_id: str - Organization ID

user_id: str - User ID

client.users.resend_invite(organization_id, user_id) -> ResendInviteResponse

📝 Description

Resends an invitation email to a user who has a pending invitation.

🔌 Usage

response = scalekit_client.users.resend_invite('org_123456', 'usr_123456')

⚙️ Parameters

organization_id: str - Organization ID containing the pending invitation

user_id: str - User ID who has a pending invitation

Role

client.roles.list_roles() -> ListRolesResponse

📝 Description

Lists all roles in the environment.

🔌 Usage

response = scalekit_client.roles.list_roles()


for role in response[0].roles:
    print(f"Role: {role.name}")
client.roles.get_role(role_name) -> GetRoleResponse

📝 Description

Retrieves role details by role name.

🔌 Usage

response = scalekit_client.roles.get_role('admin')
role = response[0].role

⚙️ Parameters

role_name: str - Role name to get role details

client.roles.create_role(role) -> CreateRoleResponse

📝 Description

Creates a new role.

🔌 Usage

from scalekit.v1.roles.roles_pb2 import CreateRole


role = CreateRole()
role.name = "editor"
role.display_name = "Editor"


response = scalekit_client.roles.create_role(role)

⚙️ Parameters

role: CreateRole - Role object with expected values for role creation

client.roles.update_role(role_name, role) -> UpdateRoleResponse

📝 Description

Updates an existing role by name.

🔌 Usage

from scalekit.v1.roles.roles_pb2 import UpdateRole


role = UpdateRole()
role.display_name = "Senior Editor"


response = scalekit_client.roles.update_role('editor', role)

⚙️ Parameters

role_name: str - Role name to update

role: UpdateRole - Role object with expected values for role update

client.roles.delete_role(role_name, reassign_role_name?)

📝 Description

Deletes a role by name.

🔌 Usage

scalekit_client.roles.delete_role('editor', reassign_role_name='viewer')

⚙️ Parameters

role_name: str - Role name to be deleted

reassign_role_name: Optional[str] - Role name to reassign users to when deleting this role

client.roles.get_role_users_count(role_name) -> GetRoleUsersCountResponse

📝 Description

Gets the count of users associated with a role.

🔌 Usage

response = scalekit_client.roles.get_role_users_count('admin')
print(f"User count: {response[0].count}")

⚙️ Parameters

role_name: str - Role name to get user count for

client.roles.list_organization_roles(org_id) -> ListOrganizationRolesResponse

📝 Description

Lists all organization-specific roles.

🔌 Usage

response = scalekit_client.roles.list_organization_roles('org_123456')


for role in response[0].roles:
    print(f"Role: {role.name}")

⚙️ Parameters

org_id: str - Organization ID

client.roles.create_organization_role(org_id, role) -> CreateOrganizationRoleResponse

📝 Description

Creates a new organization-specific role.

🔌 Usage

from scalekit.v1.roles.roles_pb2 import CreateOrganizationRole


role = CreateOrganizationRole()
role.name = "org_admin"
role.display_name = "Organization Admin"


response = scalekit_client.roles.create_organization_role('org_123456', role)

⚙️ Parameters

org_id: str - Organization ID

role: CreateOrganizationRole - Role object with expected values

client.roles.get_organization_role(org_id, role_name) -> GetOrganizationRoleResponse

📝 Description

Retrieves organization-specific role details by name.

🔌 Usage

response = scalekit_client.roles.get_organization_role('org_123456', 'org_admin')
role = response[0].role

⚙️ Parameters

org_id: str - Organization ID

role_name: str - Role name to get role details

client.roles.update_organization_role(org_id, role_name, role) -> UpdateOrganizationRoleResponse

📝 Description

Updates an existing organization-specific role.

🔌 Usage

from scalekit.v1.roles.roles_pb2 import UpdateRole


role = UpdateRole()
role.display_name = "Organization Administrator"


response = scalekit_client.roles.update_organization_role(
    'org_123456',
    'org_admin',
    role
)

⚙️ Parameters

org_id: str - Organization ID

role_name: str - Role name to update

role: UpdateRole - Role object with expected values

client.roles.delete_organization_role(org_id, role_name, reassign_role_name?)

📝 Description

Deletes an organization-specific role.

🔌 Usage

scalekit_client.roles.delete_organization_role(
    'org_123456',
    'org_admin',
    reassign_role_name='member'
)

⚙️ Parameters

org_id: str - Organization ID

role_name: str - Role name to be deleted

reassign_role_name: Optional[str] - Role name to reassign users to

Permission

client.permissions.list_permissions(page_token?, page_size?) -> ListPermissionsResponse

📝 Description

Lists all permissions with pagination support.

🔌 Usage

response = scalekit_client.permissions.list_permissions(
    page_size=50
)


for permission in response[0].permissions:
    print(f"Permission: {permission.name}")

⚙️ Parameters

page_token: Optional[str] - Token for pagination

page_size: Optional[int] - Number of permissions per page

client.permissions.get_permission(permission_name) -> GetPermissionResponse

📝 Description

Retrieves permission details by permission name.

🔌 Usage

response = scalekit_client.permissions.get_permission('write:articles')
permission = response[0].permission

⚙️ Parameters

permission_name: str - Permission name to get permission details

client.permissions.create_permission(permission) -> CreatePermissionResponse

📝 Description

Creates a new permission.

🔌 Usage

from scalekit.v1.roles.roles_pb2 import CreatePermission


permission = CreatePermission()
permission.name = "write:articles"
permission.description = "Permission to write articles"


response = scalekit_client.permissions.create_permission(permission)

⚙️ Parameters

permission: CreatePermission - Permission object with expected values

client.permissions.update_permission(permission_name, permission) -> UpdatePermissionResponse

📝 Description

Updates an existing permission by name.

🔌 Usage

from scalekit.v1.roles.roles_pb2 import CreatePermission


permission = CreatePermission()
permission.description = "Updated description"


response = scalekit_client.permissions.update_permission(
    'write:articles',
    permission
)

⚙️ Parameters

permission_name: str - Permission name to update

permission: CreatePermission - Permission object with expected values

client.permissions.delete_permission(permission_name)

📝 Description

Deletes a permission by name.

🔌 Usage

scalekit_client.permissions.delete_permission('write:articles')

⚙️ Parameters

permission_name: str - Permission name to be deleted

client.permissions.list_role_permissions(role_name) -> ListRolePermissionsResponse

📝 Description

Lists all permissions associated with a role.

🔌 Usage

response = scalekit_client.permissions.list_role_permissions('editor')


for permission in response[0].permissions:
    print(f"Permission: {permission.name}")

⚙️ Parameters

role_name: str - Role name to get permissions for

client.permissions.add_permissions_to_role(role_name, permission_names)

📝 Description

Adds permissions to a role.

🔌 Usage

scalekit_client.permissions.add_permissions_to_role(
    'editor',
    ['write:articles', 'edit:articles']
)

⚙️ Parameters

role_name: str - Role name to add permissions to

permission_names: list[str] - List of permission names to add

client.permissions.remove_permission_from_role(role_name, permission_name)

📝 Description

Removes a permission from a role.

🔌 Usage

scalekit_client.permissions.remove_permission_from_role(
    'editor',
    'write:articles'
)

⚙️ Parameters

role_name: str - Role name to remove permission from

permission_name: str - Permission name to remove

client.permissions.list_effective_role_permissions(role_name) -> ListEffectiveRolePermissionsResponse

📝 Description

Lists all effective permissions for a role including both direct and inherited permissions.

This returns the complete set of capabilities available through the role hierarchy.

🔌 Usage

response = scalekit_client.permissions.list_effective_role_permissions('senior_editor')


print(f'Total effective permissions: {len(response[0].permissions)}')

⚙️ Parameters

role_name: str - Role to analyze

Passwordless

client.passwordless.send_passwordless_email(email, template?, magiclink_auth_uri?, state?, expires_in?, template_variables?) -> SendPasswordlessResponse

📝 Description

Send a passwordless authentication email with OTP or magic link.

🔌 Usage

response = scalekit_client.passwordless.send_passwordless_email(
    'user@example.com',
    template='SIGNIN',
    state='random-state',
    expires_in=3600
)


print(f'Auth Request ID: {response[0].auth_request_id}')

⚙️ Parameters

email: str - The email address to send the passwordless link to

template: Optional[str | TemplateType] - The template type (SIGNIN/SIGNUP)

magiclink_auth_uri: Optional[str] - Optional auth URI for magic link

state: Optional[str] - Optional state parameter

expires_in: Optional[int] - Optional expiration time in seconds (default: 300)

template_variables: Optional[Dict[str, str]] - Optional template variables

client.passwordless.verify_passwordless_email(code?, link_token?, auth_request_id?) -> VerifyPasswordLessResponse

📝 Description

Verify a passwordless authentication code or link token.

🔌 Usage

response = scalekit_client.passwordless.verify_passwordless_email(
    code='123456',
    auth_request_id='auth_request_id'
)


print(f'Email: {response[0].email}')

⚙️ Parameters

code: Optional[str] - The one-time code received via email

link_token: Optional[str] - The link token received via email

auth_request_id: Optional[str] - Optional auth request ID from the send response

client.passwordless.resend_passwordless_email(auth_request_id) -> SendPasswordlessResponse

📝 Description

Resend a passwordless authentication email.

🔌 Usage

response = scalekit_client.passwordless.resend_passwordless_email('auth_request_id')

⚙️ Parameters

auth_request_id: str - The auth request ID from the original send response

WebAuthn

client.webauthn.list_credentials(user_id) -> ListCredentialsResponse

📝 Description

List all WebAuthn credentials for a user.

🔌 Usage

response = scalekit_client.webauthn.list_credentials('usr_123456')
print(f'Credentials: {response[0].credentials}')

⚙️ Parameters

user_id: str - The user ID to list credentials for

client.webauthn.update_credential(credential_id, display_name) -> UpdateCredentialResponse

📝 Description

Update a WebAuthn credential’s display name.

🔌 Usage

response = scalekit_client.webauthn.update_credential(
    'cred_123',
    'My YubiKey'
)

⚙️ Parameters

credential_id: str - The credential ID to update

display_name: str - The new display name for the credential

client.webauthn.delete_credential(credential_id) -> DeleteCredentialResponse

📝 Description

Delete a WebAuthn credential.

🔌 Usage

response = scalekit_client.webauthn.delete_credential('cred_123')
print(f'Deleted: {response[0].success}')

⚙️ Parameters

credential_id: str - The credential ID to delete

Auth

client.auth.update_login_user_details(connection_id, login_request_id, user?) -> Empty

📝 Description

Updates user details for an ongoing authentication request.

If you are using Auth for MCP solution of Scalekit in “Bring your own Auth” mode, this method helps updating Scalekit with the currently logged in user details for the ongoing authentication request.

🔌 Usage

scalekit_client.auth.update_login_user_details(
    'conn_abc123',
    'login_xyz789',
    {
        'email': 'john.doe@company.com',
        'sub': 'unique_user_id_456',
    }
)

⚙️ Parameters

connection_id: str - The SSO connection ID being used for authentication

login_request_id: str - The unique login request identifier from the auth flow

user: Optional[Mapping[str, Any]] - User details to update

  • email: Optional[str] - User’s email address
  • sub: Optional[str] - Unique user identifier (subject)
  • given_name: Optional[str] - User’s first name
  • family_name: Optional[str] - User’s last name
  • email_verified: Optional[bool] - Whether email is verified
  • phone_number: Optional[str] - User’s primary phone number
  • phone_number_verified: Optional[bool] - Whether phone is verified
  • name: Optional[str] - Full display name of the user
  • preferred_username: Optional[str] - User’s preferred username
  • picture: Optional[str] - URL to user’s profile picture
  • gender: Optional[str] - User’s gender
  • locale: Optional[str] - User’s locale preference
  • groups: Optional[list[str]] - List of group names or IDs
  • custom_attributes: Optional[dict] - Custom attributes as dict

Sessions

client.sessions.get_session(session_id) -> SessionDetails

📝 Description

Retrieves session details by session ID.

🔌 Usage

response = scalekit_client.sessions.get_session('session_123456')
session = response[0]

⚙️ Parameters

session_id: str - Session ID to get session details

client.sessions.get_user_sessions(user_id, page_size?, page_token?, filter?) -> UserSessionDetails

📝 Description

Retrieves all session details for a user with pagination and filtering support.

🔌 Usage

response = scalekit_client.sessions.get_user_sessions(
    'usr_123456',
    page_size=50
)


for session in response[0].sessions:
    print(f'Session: {session.id}')

⚙️ Parameters

user_id: str - User ID to get all session details for

page_size: Optional[int] - Number of sessions to return per page

page_token: Optional[str] - Token for pagination

filter: Optional[UserSessionFilter] - Filter to apply to sessions (status, time range)

client.sessions.revoke_session(session_id) -> RevokeSessionResponse

📝 Description

Revokes a session for a user.

🔌 Usage

response = scalekit_client.sessions.revoke_session('session_123456')

⚙️ Parameters

session_id: str - Session ID to revoke

client.sessions.revoke_all_user_sessions(user_id) -> RevokeAllUserSessionsResponse

📝 Description

Revokes all sessions for a user.

🔌 Usage

response = scalekit_client.sessions.revoke_all_user_sessions('usr_123456')

⚙️ Parameters

user_id: str - User ID to revoke all sessions for

M2M Client

client.m2m_client.list_organization_clients(organization_id, page_size?, page_token?) -> ListOrganizationClientsResponse

📝 Description

Lists all machine-to-machine clients for an organization.

🔌 Usage

response = scalekit_client.m2m_client.list_organization_clients(
    'org_123456',
    page_size=50
)


for client in response[0].clients:
    print(f'Client: {client.id}')

⚙️ Parameters

organization_id: str - Organization ID to list clients for

page_size: Optional[int] - Page size for pagination (between 10 and 100)

page_token: Optional[str] - Page token for pagination

client.m2m_client.get_organization_client(organization_id, client_id) -> GetOrganizationClientResponse

📝 Description

Retrieves an organization client by ID.

🔌 Usage

response = scalekit_client.m2m_client.get_organization_client(
    'org_123456',
    'client_123456'
)

⚙️ Parameters

organization_id: str - Organization ID

client_id: str - Client ID

client.m2m_client.create_organization_client(organization_id, m2m_client) -> CreateOrganizationClientResponse

📝 Description

Creates a new machine-to-machine client for an organization.

🔌 Usage

from scalekit.v1.clients.clients_pb2 import OrganizationClient


client = OrganizationClient()
client.name = "My M2M Client"


response = scalekit_client.m2m_client.create_organization_client(
    'org_123456',
    client
)

⚙️ Parameters

organization_id: str - Organization ID to create client for

m2m_client: OrganizationClient - Client object with desired client properties

client.m2m_client.update_organization_client(organization_id, client_id, m2m_client) -> UpdateOrganizationClientResponse

📝 Description

Updates an existing machine-to-machine client.

🔌 Usage

from scalekit.v1.clients.clients_pb2 import OrganizationClient


client = OrganizationClient()
client.name = "Updated M2M Client"


response = scalekit_client.m2m_client.update_organization_client(
    'org_123456',
    'client_123456',
    client
)

⚙️ Parameters

organization_id: str - Organization ID

client_id: str - Client ID

m2m_client: OrganizationClient - Organization Client object

client.m2m_client.delete_organization_client(organization_id, client_id) -> None

📝 Description

Deletes a machine-to-machine client from an organization.

🔌 Usage

scalekit_client.m2m_client.delete_organization_client(
    'org_123456',
    'client_123456'
)

⚙️ Parameters

organization_id: str - Organization ID

client_id: str - Client ID

client.m2m_client.add_organization_client_secret(organization_id, client_id) -> CreateOrganizationClientSecretResponse

📝 Description

Adds a new secret to an organization client.

🔌 Usage

response = scalekit_client.m2m_client.add_organization_client_secret(
    'org_123456',
    'client_123456'
)

⚙️ Parameters

organization_id: str - Organization ID

client_id: str - Client ID

client.m2m_client.remove_organization_client_secret(organization_id, client_id, secret_id) -> None

📝 Description

Removes a secret from an organization client.

🔌 Usage

scalekit_client.m2m_client.remove_organization_client_secret(
    'org_123456',
    'client_123456',
    'secret_123456'
)

⚙️ Parameters

organization_id: str - Organization ID

client_id: str - Client ID

secret_id: str - Secret ID

Connected Accounts

client.connected_accounts.list_connected_accounts(organization_id?, user_id?, connector?, identifier?, provider?, page_size?, page_token?) -> ListConnectedAccountsResponse

📝 Description

Lists all connected accounts with optional filtering.

🔌 Usage

response = scalekit_client.connected_accounts.list_connected_accounts(
    organization_id='org_123456',
    user_id='usr_123456',
    page_size=50
)


for account in response[0].connected_accounts:
    print(f'Account: {account.id}')

⚙️ Parameters

organization_id: Optional[str] - Organization ID

user_id: Optional[str] - User ID

connector: Optional[str] - Connector identifier

identifier: Optional[str] - Identifier for the connector

provider: Optional[str] - Provider name

page_size: Optional[int] - Number of results per page

page_token: Optional[str] - Page token for pagination

client.connected_accounts.get_connected_account_by_identifier(connector, identifier, organization_id?, user_id?, connected_account_id?) -> GetConnectedAccountByIdentifierResponse

📝 Description

Retrieves a connected account by identifier.

🔌 Usage

response = scalekit_client.connected_accounts.get_connected_account_by_identifier(
    'slack',
    'workspace_id',
    organization_id='org_123456',
    user_id='usr_123456'
)

⚙️ Parameters

connector: str - Connector identifier

identifier: str - Identifier for the connector

organization_id: Optional[str] - Organization ID

user_id: Optional[str] - User ID

connected_account_id: Optional[str] - ID of the connected account

client.connected_accounts.create_connected_account(connector, identifier, connected_account, organization_id?, user_id?) -> CreateConnectedAccountResponse

📝 Description

Creates a new connected account.

🔌 Usage

from scalekit.v1.connected_accounts.connected_accounts_pb2 import CreateConnectedAccount


account = CreateConnectedAccount()


response = scalekit_client.connected_accounts.create_connected_account(
    'slack',
    'workspace_id',
    account,
    organization_id='org_123456',
    user_id='usr_123456'
)

⚙️ Parameters

connector: str - Connector identifier

identifier: str - Identifier for the connector

connected_account: CreateConnectedAccount - Connected account details

organization_id: Optional[str] - Organization ID

user_id: Optional[str] - User ID

client.connected_accounts.update_connected_account(connector, identifier, connected_account, organization_id?, user_id?, connected_account_id?) -> UpdateConnectedAccountResponse

📝 Description

Updates an existing connected account.

🔌 Usage

from scalekit.v1.connected_accounts.connected_accounts_pb2 import UpdateConnectedAccount


account = UpdateConnectedAccount()


response = scalekit_client.connected_accounts.update_connected_account(
    'slack',
    'workspace_id',
    account,
    organization_id='org_123456',
    user_id='usr_123456'
)

⚙️ Parameters

connector: str - Connector identifier

identifier: str - Identifier for the connector

connected_account: UpdateConnectedAccount - Updated connected account details

organization_id: Optional[str] - Organization ID

user_id: Optional[str] - User ID

connected_account_id: Optional[str] - ID of the connected account to update

client.connected_accounts.delete_connected_account(connector, identifier, organization_id?, user_id?, connected_account_id?) -> DeleteConnectedAccountResponse

📝 Description

Deletes a connected account.

🔌 Usage

scalekit_client.connected_accounts.delete_connected_account(
    'slack',
    'workspace_id',
    organization_id='org_123456',
    user_id='usr_123456'
)

⚙️ Parameters

connector: str - Connector identifier

identifier: str - Identifier for the connector

organization_id: Optional[str] - Organization ID

user_id: Optional[str] - User ID

connected_account_id: Optional[str] - ID of the connected account to delete

client.connected_accounts.get_magic_link_for_connected_account(connector, identifier, organization_id?, user_id?, connected_account_id?) -> GetMagicLinkForConnectedAccountResponse

📝 Description

Generates a magic link for a connected account.

🔌 Usage

response = scalekit_client.connected_accounts.get_magic_link_for_connected_account(
    'slack',
    'workspace_id',
    organization_id='org_123456',
    user_id='usr_123456'
)


print(f'Magic Link: {response[0].magic_link}')

⚙️ Parameters

connector: str - Connector identifier

identifier: str - Identifier for the connector

organization_id: Optional[str] - Organization ID

user_id: Optional[str] - User ID

connected_account_id: Optional[str] - ID of the connected account

Source: View on GitHub →

Last fetched: January 24, 2026