Java SDK Reference

Table of Contents

• ScalekitClient
• Organizations
• Connections
• Users
• Domains
• Directories
• Sessions
• Roles
• Permissions
• Passwordless
• WebAuthn
• Auth
• Tokens
• M2M

The Java SDK exposes the clients and methods in the sections above through ScalekitClient. Connected Accounts, Tools, and Actions are not part of the Java public API in this release.

ScalekitClient

new ScalekitClient(siteName, clientId, clientSecret) -> ScalekitClient

📝 Description

Creates a new Scalekit client instance configured for your environment, and provides access to all API clients (organizations, users, connections, directories, API tokens, M2M clients, etc.).

🔌 Usage

import com.scalekit.ScalekitClient;

ScalekitClient client = new ScalekitClient(
  "https://<your-env>.scalekit.com",
  "<client_id>",
  "<client_secret>"
);

⚙️ Parameters

siteName: String - Your Scalekit environment URL (for example, https://<your-env>.scalekit.com)

clientId: String - OAuth client ID from your Scalekit dashboard

clientSecret: String - OAuth client secret from your Scalekit dashboard

client.organizations() -> OrganizationClient

📝 Description

Returns an OrganizationClient for managing organizations (tenants).

🔌 Usage

client.organizations().getById("org_123");

⚙️ Parameters

This method takes no parameters.

client.connections() -> ConnectionClient

📝 Description

Returns a ConnectionClient for managing SSO connections.

🔌 Usage

client.connections().listConnectionsByOrganization("org_123");

⚙️ Parameters

This method takes no parameters.

client.users() -> UserClient

📝 Description

Returns a UserClient for managing users and org memberships.

🔌 Usage

client.users().getUser("user_123");

⚙️ Parameters

This method takes no parameters.

client.domains() -> DomainClient

📝 Description

Returns a DomainClient for managing organization domains.

🔌 Usage

client.domains().listDomainsByOrganizationId("org_123");

⚙️ Parameters

This method takes no parameters.

client.directories() -> DirectoryClient

📝 Description

Returns a DirectoryClient for managing directories and directory resources (users/groups).

🔌 Usage

client.directories().listDirectories("org_123");

⚙️ Parameters

This method takes no parameters.

client.sessions() -> SessionClient

📝 Description

Returns a SessionClient for session retrieval and revocation.

🔌 Usage

client.sessions().getSession("sess_123");

⚙️ Parameters

This method takes no parameters.

client.roles() -> RoleClient

📝 Description

Returns a RoleClient for environment and organization role management.

🔌 Usage

client.roles().listRoles();

⚙️ Parameters

This method takes no parameters.

client.permissions() -> PermissionClient

📝 Description

Returns a PermissionClient for permission management and role-permission relationships.

🔌 Usage

client.permissions().listPermissions();

⚙️ Parameters

This method takes no parameters.

client.passwordless() -> PasswordlessClient

📝 Description

Returns a PasswordlessClient for passwordless auth flows (magic links / OTP).

🔌 Usage

client.passwordless().sendPasswordlessEmail("user@acme.com");

⚙️ Parameters

This method takes no parameters.

client.webAuthn() -> WebAuthnClient

📝 Description

Returns a WebAuthnClient for WebAuthn credential management.

🔌 Usage

client.webAuthn().listCredentials("user_123");

⚙️ Parameters

This method takes no parameters.

client.authentication() -> AuthClient

📝 Description

Returns an AuthClient for OAuth flows, token validation, and token exchange.

🔌 Usage

client.authentication().getClientAccessToken();

⚙️ Parameters

This method takes no parameters.

client.webhook() -> Webhook

📝 Description

Returns a Webhook verifier for validating Scalekit webhook payload signatures.

🔌 Usage

import java.util.Map;

boolean ok = client.webhook().verifyWebhookPayload(
  "whsec_...",
  headers,
  payloadBytes
);

⚙️ Parameters

This method takes no parameters.

client.webhook().verifyWebhookPayload(secret, headers, payload) -> boolean

📝 Description

Verifies the authenticity and integrity of webhook payloads from Scalekit.

This validates the HMAC signature and timestamp (5-minute tolerance window) to ensure the webhook was sent by Scalekit and hasn’t been tampered with.

🔌 Usage

import java.util.Map;

Map<String, String> headers = new java.util.HashMap<>();
headers.put("webhook-id", "<id>");
headers.put("webhook-timestamp", "<epoch_seconds>");
headers.put("webhook-signature", "v1,<base64sig>");

byte[] payload = requestBodyBytes;

boolean isValid = client.webhook().verifyWebhookPayload("whsec_...", headers, payload);

⚙️ Parameters

secret: String - Your webhook signing secret from the Scalekit dashboard (format: whsec_...)

headers: Map<String, String> - The HTTP headers from the webhook request (must include webhook-id, webhook-timestamp, webhook-signature)

payload: byte[] - The raw webhook request body bytes

new ScalekitInterceptor().verifyInterceptorPayload(secret, headers, payload) -> boolean

📝 Description

Verifies the authenticity and integrity of interceptor payloads from Scalekit.

This validates the HMAC signature and timestamp (5-minute tolerance window) to ensure the interceptor request was sent by Scalekit and hasn’t been tampered with.

🔌 Usage

import com.scalekit.webhooks.ScalekitInterceptor;
import java.util.Map;

ScalekitInterceptor interceptor = new ScalekitInterceptor();

Map<String, String> headers = new java.util.HashMap<>();
headers.put("interceptor-id", "<id>");
headers.put("interceptor-timestamp", "<epoch_seconds>");
headers.put("interceptor-signature", "v1,<base64sig>");

byte[] payload = requestBodyBytes;

boolean isValid = interceptor.verifyInterceptorPayload("insec_...", headers, payload);

⚙️ Parameters

secret: String - Your interceptor signing secret from the Scalekit dashboard

headers: Map<String, String> - The HTTP headers from the interceptor request (must include interceptor-id, interceptor-timestamp, interceptor-signature)

payload: byte[] - The raw interceptor request body bytes

client.tokens() -> TokenClient

📝 Description

Returns a TokenClient for managing API tokens (programmatic access credentials).

🔌 Usage

client.tokens().create("org_123");

⚙️ Parameters

This method takes no parameters.

client.m2m() -> M2MClient

📝 Description

Returns a M2MClient for managing machine-to-machine API clients.

🔌 Usage

client.m2m().listOrganizationClients("org_123", 20, "");

⚙️ Parameters

This method takes no parameters.

Organizations

client.organizations().create(organization) -> Organization

📝 Description

Creates a new organization (tenant).

🔌 Usage

import com.scalekit.grpc.scalekit.v1.organizations.CreateOrganization;
import com.scalekit.grpc.scalekit.v1.organizations.Organization;

CreateOrganization req = CreateOrganization.newBuilder()
  .setName("Acme Corporation")
  .build();

Organization org = client.organizations().create(req);

⚙️ Parameters

organization: CreateOrganization - The organization create request

client.organizations().getById(id) -> Organization

📝 Description

Fetches an organization by its Scalekit organization ID.

🔌 Usage

client.organizations().getById("org_123");

⚙️ Parameters

id: String - The organization ID

client.organizations().getByExternalId(externalId) -> Organization

📝 Description

Fetches an organization by its external ID.

🔌 Usage

client.organizations().getByExternalId("customer_123");

⚙️ Parameters

externalId: String - The external ID associated with the organization

client.organizations().updateById(id, organization) -> Organization

📝 Description

Updates an organization by its Scalekit organization ID.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.organizations.UpdateOrganization;

UpdateOrganization req = UpdateOrganization.newBuilder()
  .setName("Acme Corp (Updated)")
  .build();

client.organizations().updateById("org_123", req);

⚙️ Parameters

id: String - The organization ID

organization: UpdateOrganization - The organization update request

client.organizations().updateByExternalId(externalId, organization) -> Organization

📝 Description

Updates an organization by its external ID.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.organizations.UpdateOrganization;

UpdateOrganization req = UpdateOrganization.newBuilder()
  .setName("Acme Corp (Updated)")
  .build();

client.organizations().updateByExternalId("customer_123", req);

⚙️ Parameters

externalId: String - The external ID associated with the organization

organization: UpdateOrganization - The organization update request

client.organizations().deleteById(id) -> void

📝 Description

Deletes an organization by its Scalekit organization ID.

🔌 Usage

client.organizations().deleteById("org_123");

⚙️ Parameters

id: String - The organization ID

client.organizations().deleteByExternalId(externalId) -> void

📝 Description

Deletes an organization by its external ID.

🔌 Usage

client.organizations().deleteByExternalId("customer_123");

⚙️ Parameters

externalId: String - The external ID associated with the organization

client.organizations().listOrganizations(pageSize, pageToken) -> ListOrganizationsResponse

📝 Description

Lists organizations with pagination.

🔌 Usage

client.organizations().listOrganizations(20, "");

⚙️ Parameters

pageSize: int - Number of organizations per page

pageToken: String - Pagination token (empty string for first page)

client.organizations().generatePortalLink(organizationId) -> Link

📝 Description

Generates an admin portal link for an organization.

🔌 Usage

client.organizations().generatePortalLink("org_123");

⚙️ Parameters

organizationId: String - The organization ID

client.organizations().generatePortalLink(organizationId, features) -> Link

📝 Description

Generates an admin portal link for an organization, optionally scoped to specific portal features.

🔌 Usage

import java.util.Arrays;
import com.scalekit.grpc.scalekit.v1.organizations.Feature;

client.organizations().generatePortalLink(
  "org_123",
  Arrays.asList(Feature.FEATURE_USERS, Feature.FEATURE_CONNECTIONS)
);

⚙️ Parameters

organizationId: String - The organization ID

features: List<Feature> - The portal features to include in the link

client.organizations().updateOrganizationSettings(organizationId, settings) -> Organization

📝 Description

Updates organization settings features.

🔌 Usage

import java.util.Collections;
import com.scalekit.grpc.scalekit.v1.organizations.OrganizationSettingsFeature;

client.organizations().updateOrganizationSettings(
  "org_123",
  Collections.emptyList()
);

⚙️ Parameters

organizationId: String - The organization ID

settings: List<OrganizationSettingsFeature> - The settings features to apply

client.organizations().upsertUserManagementSettings(organizationId, settings) -> OrganizationUserManagementSettings

📝 Description

Creates or updates user management settings for an organization.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.organizations.OrganizationUserManagementSettings;

OrganizationUserManagementSettings settings =
  OrganizationUserManagementSettings.newBuilder().build();

client.organizations().upsertUserManagementSettings("org_123", settings);

⚙️ Parameters

organizationId: String - The organization ID

settings: OrganizationUserManagementSettings - The user management settings to upsert

Connections

client.connections().getConnectionById(connectionId, organizationId) -> Connection

📝 Description

Fetches a connection by ID within an organization.

🔌 Usage

client.connections().getConnectionById("conn_123", "org_123");

⚙️ Parameters

connectionId: String - The connection ID

organizationId: String - The organization ID

client.connections().listConnectionsByDomain(domain) -> ListConnectionsResponse

📝 Description

Lists connections by domain.

🔌 Usage

client.connections().listConnectionsByDomain("acme.com");

⚙️ Parameters

domain: String - The domain name (for example, acme.com)

client.connections().listConnectionsByOrganization(organizationId) -> ListConnectionsResponse

📝 Description

Lists connections for an organization.

🔌 Usage

client.connections().listConnectionsByOrganization("org_123");

⚙️ Parameters

organizationId: String - The organization ID

client.connections().enableConnection(connectionId, organizationId) -> ToggleConnectionResponse

📝 Description

Enables a connection within an organization.

🔌 Usage

client.connections().enableConnection("conn_123", "org_123");

⚙️ Parameters

connectionId: String - The connection ID

organizationId: String - The organization ID

client.connections().disableConnection(connectionId, organizationId) -> ToggleConnectionResponse

📝 Description

Disables a connection within an organization.

🔌 Usage

client.connections().disableConnection("conn_123", "org_123");

⚙️ Parameters

connectionId: String - The connection ID

organizationId: String - The organization ID

client.connections().createConnection(organizationId, connection) -> Connection

📝 Description

Creates a new connection for an organization.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.connections.CreateConnection;

CreateConnection req = CreateConnection.newBuilder()
  .setDisplayName("Acme Okta")
  .build();

client.connections().createConnection("org_123", req);

⚙️ Parameters

organizationId: String - The organization ID

connection: CreateConnection - The connection create request

client.connections().deleteConnection(connectionId, organizationId) -> void

📝 Description

Deletes a connection within an organization.

🔌 Usage

client.connections().deleteConnection("conn_123", "org_123");

⚙️ Parameters

connectionId: String - The connection ID

organizationId: String - The organization ID

Users

client.users().createUserAndMembership(organizationId, request) -> CreateUserAndMembershipResponse

📝 Description

Creates a user and an organization membership in one call.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.users.CreateUserAndMembershipRequest;

CreateUserAndMembershipRequest req = CreateUserAndMembershipRequest.newBuilder()
  .setEmail("user@acme.com")
  .build();

client.users().createUserAndMembership("org_123", req);

⚙️ Parameters

organizationId: String - The organization ID

request: CreateUserAndMembershipRequest - Create user + membership request

client.users().getUser(userId) -> GetUserResponse

📝 Description

Gets a user by user ID.

🔌 Usage

client.users().getUser("user_123");

⚙️ Parameters

userId: String - The user ID

client.users().listUsers(request) -> ListUsersResponse

📝 Description

Lists users based on a request filter.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.users.ListUsersRequest;

ListUsersRequest req = ListUsersRequest.newBuilder()
  .setPageSize(20)
  .build();

client.users().listUsers(req);

⚙️ Parameters

request: ListUsersRequest - List users request (pagination + filters)

client.users().updateUser(userId, request) -> UpdateUserResponse

📝 Description

Updates a user by user ID.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.users.UpdateUserRequest;

UpdateUserRequest req = UpdateUserRequest.newBuilder()
  .setGivenName("Jane")
  .build();

client.users().updateUser("user_123", req);

⚙️ Parameters

userId: String - The user ID

request: UpdateUserRequest - Update user request

client.users().deleteUser(userId) -> void

📝 Description

Deletes a user by user ID.

🔌 Usage

client.users().deleteUser("user_123");

⚙️ Parameters

userId: String - The user ID

client.users().createMembership(organizationId, userId, request) -> CreateMembershipResponse

📝 Description

Creates an organization membership for a user.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.users.CreateMembershipRequest;

CreateMembershipRequest req = CreateMembershipRequest.newBuilder().build();

client.users().createMembership("org_123", "user_123", req);

⚙️ Parameters

organizationId: String - The organization ID

userId: String - The user ID

request: CreateMembershipRequest - Create membership request

client.users().deleteMembership(organizationId, userId) -> void

📝 Description

Deletes an organization membership for a user.

🔌 Usage

client.users().deleteMembership("org_123", "user_123");

⚙️ Parameters

organizationId: String - The organization ID

userId: String - The user ID

client.users().updateMembership(organizationId, userId, request) -> UpdateMembershipResponse

📝 Description

Updates an organization membership for a user.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.users.UpdateMembershipRequest;

UpdateMembershipRequest req = UpdateMembershipRequest.newBuilder().build();

client.users().updateMembership("org_123", "user_123", req);

⚙️ Parameters

organizationId: String - The organization ID

userId: String - The user ID

request: UpdateMembershipRequest - Update membership request

client.users().listOrganizationUsers(organizationId, request) -> ListOrganizationUsersResponse

📝 Description

Lists users for a given organization.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.users.ListOrganizationUsersRequest;

ListOrganizationUsersRequest req = ListOrganizationUsersRequest.newBuilder()
  .setPageSize(20)
  .build();

client.users().listOrganizationUsers("org_123", req);

⚙️ Parameters

organizationId: String - The organization ID

request: ListOrganizationUsersRequest - List organization users request

client.users().resendInvite(organizationId, userId) -> ResendInviteResponse

📝 Description

Resends an invite to a user for a given organization.

🔌 Usage

client.users().resendInvite("org_123", "user_123");

⚙️ Parameters

organizationId: String - The organization ID

userId: String - The user ID

Domains

client.domains().createDomain(organizationId, domainName) -> Domain

📝 Description

Creates a domain for an organization.

🔌 Usage

client.domains().createDomain("org_123", "acme.com");

⚙️ Parameters

organizationId: String - The organization ID

domainName: String - The domain name (for example, acme.com)

client.domains().createDomain(organizationId, domainName, domainType) -> Domain

📝 Description

Creates a domain for an organization with a specified domain type.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.domains.DomainType;

client.domains().createDomain("org_123", "acme.com", DomainType.DOMAIN_TYPE_PRIMARY);

⚙️ Parameters

organizationId: String - The organization ID

domainName: String - The domain name

domainType: DomainType - The domain type

client.domains().createDomain(request) -> Domain

📝 Description

Creates a domain using a request object.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.domains.CreateDomainRequest;

CreateDomainRequest req = CreateDomainRequest.newBuilder()
  .setOrganizationId("org_123")
  .setDomain("acme.com")
  .build();

client.domains().createDomain(req);

⚙️ Parameters

request: CreateDomainRequest - The create domain request

client.domains().getDomainById(organizationId, domainId) -> Domain

📝 Description

Gets a domain by ID for an organization.

🔌 Usage

client.domains().getDomainById("org_123", "dom_123");

⚙️ Parameters

organizationId: String - The organization ID

domainId: String - The domain ID

client.domains().listDomainsByOrganizationId(organizationId) -> List<Domain>

📝 Description

Lists domains for an organization.

🔌 Usage

client.domains().listDomainsByOrganizationId("org_123");

⚙️ Parameters

organizationId: String - The organization ID

client.domains().listDomainsByOrganizationId(organizationId, domainType) -> List<Domain>

📝 Description

Lists domains for an organization filtered by domain type.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.domains.DomainType;

client.domains().listDomainsByOrganizationId("org_123", DomainType.DOMAIN_TYPE_PRIMARY);

⚙️ Parameters

organizationId: String - The organization ID

domainType: DomainType - The domain type to filter by

client.domains().deleteDomain(organizationId, domainId) -> void

📝 Description

Deletes a domain by ID for an organization.

🔌 Usage

client.domains().deleteDomain("org_123", "dom_123");

⚙️ Parameters

organizationId: String - The organization ID

domainId: String - The domain ID

Directories

client.directories().getDirectory(directoryId, organizationId) -> Directory

📝 Description

Gets a directory by ID within an organization.

🔌 Usage

client.directories().getDirectory("dir_123", "org_123");

⚙️ Parameters

directoryId: String - The directory ID

organizationId: String - The organization ID

client.directories().listDirectories(organizationId) -> ListDirectoriesResponse

📝 Description

Lists directories for an organization.

🔌 Usage

client.directories().listDirectories("org_123");

⚙️ Parameters

organizationId: String - The organization ID

client.directories().listDirectoryUsers(directoryId, organizationId, options) -> ListDirectoryUserResponse

📝 Description

Lists directory users with pagination and optional filtering, returning a Java-friendly wrapper response.

🔌 Usage

import com.scalekit.api.util.ListDirectoryResourceOptions;
import com.scalekit.api.util.ListDirectoryUserResponse;

ListDirectoryResourceOptions options = ListDirectoryResourceOptions.builder()
  .pageSize(50)
  .includeDetail(true)
  .build();

ListDirectoryUserResponse res = client.directories().listDirectoryUsers("dir_123", "org_123", options);

⚙️ Parameters

directoryId: String - The directory ID

organizationId: String - The organization ID

options: ListDirectoryResourceOptions - Options for listing directory resources

• pageSize: int - Page size
• pageToken: String - Page token
• includeDetail: boolean - Include raw SCIM detail payloads (if available)
• updatedAfter: Timestamp - Filter resources updated after this time

client.directories().listDirectoryGroups(directoryId, organizationId, options) -> ListDirectoryGroupResponse

📝 Description

Lists directory groups with pagination and optional filtering, returning a Java-friendly wrapper response.

🔌 Usage

import com.scalekit.api.util.ListDirectoryGroupResponse;
import com.scalekit.api.util.ListDirectoryResourceOptions;

ListDirectoryResourceOptions options = ListDirectoryResourceOptions.builder()
  .pageSize(50)
  .includeDetail(true)
  .build();

ListDirectoryGroupResponse res = client.directories().listDirectoryGroups("dir_123", "org_123", options);

⚙️ Parameters

directoryId: String - The directory ID

organizationId: String - The organization ID

options: ListDirectoryResourceOptions - Options for listing directory resources

• pageSize: int - Page size
• pageToken: String - Page token
• includeDetail: boolean - Include raw SCIM detail payloads (if available)
• updatedAfter: Timestamp - Filter resources updated after this time

client.directories().enableDirectory(directoryId, organizationId) -> ToggleDirectoryResponse

📝 Description

Enables a directory within an organization.

🔌 Usage

client.directories().enableDirectory("dir_123", "org_123");

⚙️ Parameters

directoryId: String - The directory ID

organizationId: String - The organization ID

client.directories().disableDirectory(directoryId, organizationId) -> ToggleDirectoryResponse

📝 Description

Disables a directory within an organization.

🔌 Usage

client.directories().disableDirectory("dir_123", "org_123");

⚙️ Parameters

directoryId: String - The directory ID

organizationId: String - The organization ID

client.directories().getPrimaryDirectoryByOrganizationId(organizationId) -> Directory

📝 Description

Gets the primary directory for an organization.

🔌 Usage

client.directories().getPrimaryDirectoryByOrganizationId("org_123");

⚙️ Parameters

organizationId: String - The organization ID

client.directories().createDirectory(organizationId, directory) -> Directory

📝 Description

Creates a directory for an organization.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.directories.CreateDirectory;

CreateDirectory req = CreateDirectory.newBuilder()
  .setDisplayName("Acme SCIM Directory")
  .build();

client.directories().createDirectory("org_123", req);

⚙️ Parameters

organizationId: String - The organization ID

directory: CreateDirectory - The directory create request

client.directories().deleteDirectory(directoryId, organizationId) -> void

📝 Description

Deletes a directory within an organization.

🔌 Usage

client.directories().deleteDirectory("dir_123", "org_123");

⚙️ Parameters

directoryId: String - The directory ID

organizationId: String - The organization ID

Sessions

client.sessions().getSession(sessionId) -> SessionDetails

📝 Description

Gets session details by session ID.

🔌 Usage

client.sessions().getSession("sess_123");

⚙️ Parameters

sessionId: String - The session ID

client.sessions().getUserSessions(userId, pageSize, pageToken, filter) -> UserSessionDetails

📝 Description

Lists sessions for a user with pagination and optional filtering.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.sessions.UserSessionFilter;

UserSessionFilter filter = UserSessionFilter.newBuilder().build();

client.sessions().getUserSessions("user_123", 20, "", filter);

⚙️ Parameters

userId: String - The user ID

pageSize: Integer - Number of sessions per page

pageToken: String - Pagination token (empty string for first page)

filter: UserSessionFilter - Optional filter criteria

client.sessions().revokeSession(sessionId) -> RevokeSessionResponse

📝 Description

Revokes a session by session ID.

🔌 Usage

client.sessions().revokeSession("sess_123");

⚙️ Parameters

sessionId: String - The session ID

client.sessions().revokeAllUserSessions(userId) -> RevokeAllUserSessionsResponse

📝 Description

Revokes all sessions for a user.

🔌 Usage

client.sessions().revokeAllUserSessions("user_123");

⚙️ Parameters

userId: String - The user ID

Roles

client.roles().createRole(request) -> CreateRoleResponse

📝 Description

Creates an environment-level role.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.roles.CreateRoleRequest;

CreateRoleRequest req = CreateRoleRequest.newBuilder().build();
client.roles().createRole(req);

⚙️ Parameters

request: CreateRoleRequest - Create role request

client.roles().getRole(roleName) -> GetRoleResponse

📝 Description

Gets an environment-level role by role name.

🔌 Usage

client.roles().getRole("admin");

⚙️ Parameters

roleName: String - Role name

client.roles().listRoles() -> ListRolesResponse

📝 Description

Lists environment-level roles.

🔌 Usage

client.roles().listRoles();

⚙️ Parameters

This method takes no parameters.

client.roles().updateRole(roleName, request) -> UpdateRoleResponse

📝 Description

Updates an environment-level role by role name.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.roles.UpdateRoleRequest;

UpdateRoleRequest req = UpdateRoleRequest.newBuilder().build();
client.roles().updateRole("admin", req);

⚙️ Parameters

roleName: String - Role name

request: UpdateRoleRequest - Update role request

client.roles().deleteRole(roleName) -> void

📝 Description

Deletes an environment-level role by role name.

🔌 Usage

client.roles().deleteRole("admin");

⚙️ Parameters

roleName: String - Role name

client.roles().deleteRole(roleName, reassignRoleName) -> void

📝 Description

Deletes an environment-level role, optionally reassigning users to another role.

🔌 Usage

client.roles().deleteRole("old_role", "new_role");

⚙️ Parameters

roleName: String - Role name to delete

reassignRoleName: String - Role name to reassign users to

client.roles().getRoleUsersCount(roleName) -> GetRoleUsersCountResponse

📝 Description

Gets the number of users assigned to an environment-level role.

🔌 Usage

client.roles().getRoleUsersCount("admin");

⚙️ Parameters

roleName: String - Role name

client.roles().createOrganizationRole(orgId, request) -> CreateOrganizationRoleResponse

📝 Description

Creates an organization-level role.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.roles.CreateOrganizationRoleRequest;

CreateOrganizationRoleRequest req = CreateOrganizationRoleRequest.newBuilder().build();
client.roles().createOrganizationRole("org_123", req);

⚙️ Parameters

orgId: String - The organization ID

request: CreateOrganizationRoleRequest - Create organization role request

client.roles().getOrganizationRole(orgId, roleName) -> GetOrganizationRoleResponse

📝 Description

Gets an organization-level role by name.

🔌 Usage

client.roles().getOrganizationRole("org_123", "org_admin");

⚙️ Parameters

orgId: String - The organization ID

roleName: String - Role name

client.roles().listOrganizationRoles(orgId) -> ListOrganizationRolesResponse

📝 Description

Lists organization-level roles.

🔌 Usage

client.roles().listOrganizationRoles("org_123");

⚙️ Parameters

orgId: String - The organization ID

client.roles().updateOrganizationRole(orgId, roleName, request) -> UpdateOrganizationRoleResponse

📝 Description

Updates an organization-level role by name.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.roles.UpdateOrganizationRoleRequest;

UpdateOrganizationRoleRequest req = UpdateOrganizationRoleRequest.newBuilder().build();
client.roles().updateOrganizationRole("org_123", "org_admin", req);

⚙️ Parameters

orgId: String - The organization ID

roleName: String - Role name

request: UpdateOrganizationRoleRequest - Update organization role request

client.roles().deleteOrganizationRole(orgId, roleName) -> void

📝 Description

Deletes an organization-level role by name.

🔌 Usage

client.roles().deleteOrganizationRole("org_123", "org_admin");

⚙️ Parameters

orgId: String - The organization ID

roleName: String - Role name

client.roles().deleteOrganizationRole(orgId, roleName, reassignRoleName) -> void

📝 Description

Deletes an organization-level role, optionally reassigning users to another role.

🔌 Usage

client.roles().deleteOrganizationRole("org_123", "old_role", "new_role");

⚙️ Parameters

orgId: String - The organization ID

roleName: String - Role name to delete

reassignRoleName: String - Role name to reassign users to

client.roles().updateDefaultOrganizationRoles(orgId, request) -> UpdateDefaultOrganizationRolesResponse

📝 Description

Updates the default organization roles configuration.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.roles.UpdateDefaultOrganizationRolesRequest;

UpdateDefaultOrganizationRolesRequest req = UpdateDefaultOrganizationRolesRequest.newBuilder().build();
client.roles().updateDefaultOrganizationRoles("org_123", req);

⚙️ Parameters

orgId: String - The organization ID

request: UpdateDefaultOrganizationRolesRequest - Update default roles request

client.roles().deleteRoleBase(roleName) -> void

📝 Description

Deletes a role base by role name.

🔌 Usage

client.roles().deleteRoleBase("admin");

⚙️ Parameters

roleName: String - Role name

Permissions

client.permissions().createPermission(request) -> CreatePermissionResponse

📝 Description

Creates a permission.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.roles.CreatePermissionRequest;

CreatePermissionRequest req = CreatePermissionRequest.newBuilder().build();
client.permissions().createPermission(req);

⚙️ Parameters

request: CreatePermissionRequest - Create permission request

client.permissions().getPermission(permissionName) -> GetPermissionResponse

📝 Description

Gets a permission by name.

🔌 Usage

client.permissions().getPermission("read:documents");

⚙️ Parameters

permissionName: String - Permission name

client.permissions().listPermissions() -> ListPermissionsResponse

📝 Description

Lists permissions.

🔌 Usage

client.permissions().listPermissions();

⚙️ Parameters

This method takes no parameters.

client.permissions().listPermissions(pageToken) -> ListPermissionsResponse

📝 Description

Lists permissions using a pagination token.

🔌 Usage

client.permissions().listPermissions("next_page_token");

⚙️ Parameters

pageToken: String - Pagination token

client.permissions().updatePermission(permissionName, request) -> UpdatePermissionResponse

📝 Description

Updates a permission by name.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.roles.UpdatePermissionRequest;

UpdatePermissionRequest req = UpdatePermissionRequest.newBuilder().build();
client.permissions().updatePermission("read:documents", req);

⚙️ Parameters

permissionName: String - Permission name

request: UpdatePermissionRequest - Update permission request

client.permissions().deletePermission(permissionName) -> void

📝 Description

Deletes a permission by name.

🔌 Usage

client.permissions().deletePermission("read:documents");

⚙️ Parameters

permissionName: String - Permission name

client.permissions().listRolePermissions(roleName) -> ListRolePermissionsResponse

📝 Description

Lists permissions directly assigned to a role.

🔌 Usage

client.permissions().listRolePermissions("admin");

⚙️ Parameters

roleName: String - Role name

client.permissions().addPermissionsToRole(roleName, request) -> AddPermissionsToRoleResponse

📝 Description

Adds permissions to a role.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.roles.AddPermissionsToRoleRequest;

AddPermissionsToRoleRequest req = AddPermissionsToRoleRequest.newBuilder().build();
client.permissions().addPermissionsToRole("admin", req);

⚙️ Parameters

roleName: String - Role name

request: AddPermissionsToRoleRequest - Add permissions to role request

client.permissions().removePermissionFromRole(roleName, permissionName) -> void

📝 Description

Removes a permission from a role.

🔌 Usage

client.permissions().removePermissionFromRole("admin", "read:documents");

⚙️ Parameters

roleName: String - Role name

permissionName: String - Permission name

client.permissions().listEffectiveRolePermissions(roleName) -> ListEffectiveRolePermissionsResponse

📝 Description

Lists effective permissions for a role, including inherited permissions.

🔌 Usage

client.permissions().listEffectiveRolePermissions("admin");

⚙️ Parameters

roleName: String - Role name

Passwordless

client.passwordless().sendPasswordlessEmail(email, options) -> SendPasswordlessResponse

📝 Description

Sends a passwordless authentication email (magic link / OTP depending on template).

🔌 Usage

import com.scalekit.internal.http.SendPasswordlessOptions;

SendPasswordlessOptions options = new SendPasswordlessOptions();
options.setState("opaque-state");

client.passwordless().sendPasswordlessEmail("user@acme.com", options);

⚙️ Parameters

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

options: SendPasswordlessOptions - Options for sending the passwordless email

• template: TemplateType - Email template type
• state: String - Opaque state value
• magiclinkAuthUri: String - Magiclink auth URI override
• expiresIn: Integer - Expiration in seconds
• templateVariables: Map<String, String> - Template variables

client.passwordless().sendPasswordlessEmail(email) -> SendPasswordlessResponse

📝 Description

Sends a passwordless authentication email with default options.

🔌 Usage

client.passwordless().sendPasswordlessEmail("user@acme.com");

⚙️ Parameters

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

client.passwordless().verifyPasswordlessEmail(credential, authRequestId) -> VerifyPasswordLessResponse

📝 Description

Verifies a passwordless authentication code or link token.

🔌 Usage

import com.scalekit.internal.http.VerifyPasswordlessOptions;

VerifyPasswordlessOptions credential = new VerifyPasswordlessOptions();
credential.setCode("123456");

client.passwordless().verifyPasswordlessEmail(credential, "authreq_123");

⚙️ Parameters

credential: VerifyPasswordlessOptions - Credential payload

• code: String - One-time code (OTP)
• linkToken: String - Magic link token
• authRequestId: String - Optional auth request ID

authRequestId: String - Optional auth request ID from the send response

client.passwordless().verifyPasswordlessEmail(credential) -> VerifyPasswordLessResponse

📝 Description

Verifies a passwordless authentication code or link token without supplying an auth request ID argument.

🔌 Usage

import com.scalekit.internal.http.VerifyPasswordlessOptions;

VerifyPasswordlessOptions credential = new VerifyPasswordlessOptions();
credential.setLinkToken("<magic_link_token>");

client.passwordless().verifyPasswordlessEmail(credential);

⚙️ Parameters

credential: VerifyPasswordlessOptions - Credential payload

• code: String - One-time code (OTP)
• linkToken: String - Magic link token
• authRequestId: String - Optional auth request ID

client.passwordless().resendPasswordlessEmail(authRequestId) -> SendPasswordlessResponse

📝 Description

Resends a passwordless authentication email.

🔌 Usage

client.passwordless().resendPasswordlessEmail("authreq_123");

⚙️ Parameters

authRequestId: String - The auth request ID from the original send response

WebAuthn

client.webAuthn().listCredentials(userId) -> ListCredentialsResponse

📝 Description

Lists all WebAuthn credentials for a user.

🔌 Usage

client.webAuthn().listCredentials("user_123");

⚙️ Parameters

userId: String - The user ID

client.webAuthn().updateCredential(credentialId, displayName) -> UpdateCredentialResponse

📝 Description

Updates a WebAuthn credential’s display name.

🔌 Usage

client.webAuthn().updateCredential("cred_123", "My laptop key");

⚙️ Parameters

credentialId: String - Credential ID

displayName: String - New display name for the credential

client.webAuthn().deleteCredential(credentialId) -> DeleteCredentialResponse

📝 Description

Deletes a WebAuthn credential.

🔌 Usage

client.webAuthn().deleteCredential("cred_123");

⚙️ Parameters

credentialId: String - Credential ID

Auth

client.authentication().getAuthorizationUrl(redirectUri, options) -> URL

📝 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 that you can redirect your users to.

🔌 Usage

import com.scalekit.internal.http.AuthorizationUrlOptions;
import java.net.URL;

AuthorizationUrlOptions options = new AuthorizationUrlOptions();
options.setOrganizationId("org_123");
options.setState("random-state-value");

URL authUrl = client.authentication().getAuthorizationUrl(
  "https://yourapp.com/auth/callback",
  options
);

⚙️ Parameters

redirectUri: String - 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

• connectionId: String - Specific SSO connection ID to use for authentication
• organizationId: String - Organization ID to authenticate against
• scopes: List<String> - OAuth scopes to request (default: openid profile email)
• state: String - Opaque value to maintain state between request and callback
• nonce: String - String value used to associate a client session with an ID Token
• domainHint: String - Domain hint to identify which organization’s IdP to use
• loginHint: String - Hint about the login identifier the user might use
• codeChallenge: String - PKCE code challenge for enhanced security
• codeChallengeMethod: String - Method used to generate the code challenge (S256)
• provider: String - Social login provider (for example, google, github, microsoft)
• prompt: String - Controls authentication behavior (for example, login, consent, create)

client.authentication().getLogoutUrl(options) -> URL

📝 Description

Utility method to generate the OAuth 2.0 logout URL to initiate the logout flow.

This method doesn’t make any network calls but instead generates a fully formed logout URL that you can redirect your users to for logging out.

🔌 Usage

import com.scalekit.internal.http.LogoutUrlOptions;
import java.net.URL;

LogoutUrlOptions options = new LogoutUrlOptions();
options.setIdTokenHint(user.getIdToken());
options.setPostLogoutRedirectUri("https://yourapp.com");
options.setState("random-state-value");

URL logoutUrl = client.authentication().getLogoutUrl(options);

⚙️ Parameters

options: LogoutUrlOptions - Configuration for the logout request

• idTokenHint: String - ID token hint to identify the user to log out
• postLogoutRedirectUri: String - URL to redirect the user to after logout (optional)
• state: String - Opaque value to maintain state between request and callback (optional)

client.authentication().authenticateWithCode(code, redirectUri, options) -> AuthenticationResponse

📝 Description

Exchanges an authorization code for access tokens and ID token information.

🔌 Usage

import com.scalekit.internal.http.AuthenticationOptions;
import com.scalekit.internal.http.AuthenticationResponse;

AuthenticationResponse result = client.authentication().authenticateWithCode(
  "<code>",
  "https://yourapp.com/auth/callback",
  new AuthenticationOptions()
);

String accessToken = result.getAccessToken();

⚙️ Parameters

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

redirectUri: String - The same redirect URI used in getAuthorizationUrl(). Must match exactly.

options: AuthenticationOptions - Optional authentication configuration

• codeVerifier: String - PKCE code verifier (required if PKCE was used)

client.authentication().getIdpInitiatedLoginClaims(idpInitiatedLoginToken) -> IdpInitiatedLoginClaims

📝 Description

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

🔌 Usage

import com.scalekit.internal.http.IdpInitiatedLoginClaims;

IdpInitiatedLoginClaims claims = client.authentication().getIdpInitiatedLoginClaims("<idp_initiated_login_token>");

⚙️ Parameters

idpInitiatedLoginToken: String - The IdP initiated login token

client.authentication().refreshAccessToken(refreshToken) -> AuthenticationResponse

📝 Description

Refreshes access credentials using a refresh token.

🔌 Usage

client.authentication().refreshAccessToken("<refresh_token>");

⚙️ Parameters

refreshToken: String - The refresh token

client.authentication().validateAccessToken(jwt) -> boolean

📝 Description

Validates an access token’s signature and expiry.

🔌 Usage

boolean ok = client.authentication().validateAccessToken("<access_token_jwt>");

⚙️ Parameters

jwt: String - The access token JWT

client.authentication().validateAccessTokenAndGetClaims(jwt) -> Map<String, Object>

📝 Description

Validates an access token and returns decoded claims as a map.

🔌 Usage

import java.util.Map;

Map<String, Object> claims = client.authentication().validateAccessTokenAndGetClaims("<access_token_jwt>");

⚙️ Parameters

jwt: String - The access token JWT

client.authentication().getClientAccessToken() -> String

📝 Description

Fetches an access token using the client credentials grant (machine-to-machine).

🔌 Usage

String token = client.authentication().getClientAccessToken();

⚙️ Parameters

This method takes no parameters.

Tokens

client.tokens().create(organizationId) -> CreateTokenResponse

📝 Description

Creates a new API token for an organization with default settings.

🔌 Usage

client.tokens().create("org_123");

⚙️ Parameters

organizationId: String - The organization ID to scope the token to

client.tokens().create(organizationId, userId, customClaims, expiry, description) -> CreateTokenResponse

📝 Description

Creates a new API token for an organization with custom options.

🔌 Usage

import java.util.HashMap;
import java.util.Map;
import com.google.protobuf.Timestamp;

Map<String, String> claims = new HashMap<>();
claims.put("environment", "production");

Timestamp expiry = Timestamp.newBuilder()
  .setSeconds(System.currentTimeMillis() / 1000 + 86400)
  .build();

client.tokens().create("org_123", "user_123", claims, expiry, "Production access token");

⚙️ Parameters

organizationId: String - The organization ID to scope the token to

userId: String - Optional user ID to scope the token to a specific user

customClaims: Map<String, String> - Optional custom claims key-value pairs

expiry: Timestamp - Optional expiry timestamp

description: String - Optional human-readable description

client.tokens().validate(token) -> ValidateTokenResponse

📝 Description

Validates an API token and returns associated context.

🔌 Usage

client.tokens().validate("apit_xxxxx");

⚙️ Parameters

token: String - The opaque token string or token ID (format: apit_xxxxx)

client.tokens().invalidate(token) -> void

📝 Description

Invalidates (soft deletes) an API token. This operation is idempotent - it succeeds even if the token was already invalidated.

🔌 Usage

client.tokens().invalidate("apit_xxxxx");

⚙️ Parameters

token: String - The opaque token string or token ID (format: apit_xxxxx)

client.tokens().update(token, customClaims, description) -> UpdateTokenResponse

📝 Description

Updates custom claims and/or description of an existing API token. Custom claims are merged into the existing set. To remove a claim, set its value to an empty string.

🔌 Usage

import java.util.HashMap;
import java.util.Map;

Map<String, String> newClaims = new HashMap<>();
newClaims.put("environment", "staging");
newClaims.put("old_claim", "");  // Remove this claim

client.tokens().update("apit_xxxxx", newClaims, "Updated description");

⚙️ Parameters

token: String - The opaque token string or token ID (format: apit_xxxxx)

customClaims: Map<String, String> - Claims to merge; set value to "" to remove a claim

description: String - Replacement description; null leaves unchanged, empty string clears it

client.tokens().list(organizationId, pageSize, pageToken) -> ListTokensResponse

📝 Description

Lists API tokens for an organization with pagination.

🔌 Usage

client.tokens().list("org_123", 20, "");

⚙️ Parameters

organizationId: String - The organization ID to list tokens for

pageSize: int - Page size (default 10, max 30)

pageToken: String - Pagination cursor for next page (empty string for first page)

client.tokens().list(organizationId, userId, pageSize, pageToken) -> ListTokensResponse

📝 Description

Lists API tokens for an organization and user with pagination.

🔌 Usage

client.tokens().list("org_123", "user_123", 20, "");

⚙️ Parameters

organizationId: String - The organization ID to list tokens for

userId: String - The user ID to filter tokens for

pageSize: int - Page size (default 10, max 30)

pageToken: String - Pagination cursor for next page (empty string for first page)

M2M

client.m2m().createOrganizationClient(organizationId, client) -> CreateOrganizationClientResponse

📝 Description

Creates a new M2M (machine-to-machine) API client for an organization. The plain secret is returned only at creation time and cannot be retrieved again.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.clients.OrganizationClient;

OrganizationClient orgClient = OrganizationClient.newBuilder()
  .setName("Production Service Account")
  .build();

client.m2m().createOrganizationClient("org_123", orgClient);

⚙️ Parameters

organizationId: String - The organization ID to create the client for

client: OrganizationClient - Organization client proto with desired properties (name, scopes, audience, customClaims)

client.m2m().getOrganizationClient(organizationId, clientId) -> GetOrganizationClientResponse

📝 Description

Retrieves details of a specific M2M client.

🔌 Usage

client.m2m().getOrganizationClient("org_123", "skc_xxxxx");

⚙️ Parameters

organizationId: String - The organization ID

clientId: String - The client ID (format: skc_xxxxx)

client.m2m().updateOrganizationClient(organizationId, clientId, client) -> UpdateOrganizationClientResponse

📝 Description

Updates the configuration of an existing M2M client.

🔌 Usage

import com.scalekit.grpc.scalekit.v1.clients.OrganizationClient;

OrganizationClient updates = OrganizationClient.newBuilder()
  .setName("Updated Service Account Name")
  .build();

client.m2m().updateOrganizationClient("org_123", "skc_xxxxx", updates);

⚙️ Parameters

organizationId: String - The organization ID

clientId: String - The client ID to update

client: OrganizationClient - Organization client proto with fields to update

client.m2m().deleteOrganizationClient(organizationId, clientId) -> void

📝 Description

Permanently deletes an M2M client from an organization. This operation cannot be undone and all associated secrets are invalidated.

🔌 Usage

client.m2m().deleteOrganizationClient("org_123", "skc_xxxxx");

⚙️ Parameters

organizationId: String - The organization ID

clientId: String - The client ID to delete

client.m2m().createOrganizationClientSecret(organizationId, clientId) -> CreateOrganizationClientSecretResponse

📝 Description

Creates a new secret for an M2M client. The plain secret value is returned only at creation time and cannot be retrieved again.

🔌 Usage

client.m2m().createOrganizationClientSecret("org_123", "skc_xxxxx");

⚙️ Parameters

organizationId: String - The organization ID

clientId: String - The client ID to add a secret to

client.m2m().deleteOrganizationClientSecret(organizationId, clientId, secretId) -> void

📝 Description

Permanently deletes a secret from an M2M client.

🔌 Usage

client.m2m().deleteOrganizationClientSecret("org_123", "skc_xxxxx", "sks_xxxxx");

⚙️ Parameters

organizationId: String - The organization ID

clientId: String - The client ID

secretId: String - The secret ID to delete

client.m2m().listOrganizationClients(organizationId, pageSize, pageToken) -> ListOrganizationClientsResponse

📝 Description

Lists all M2M clients for an organization with pagination.

🔌 Usage

client.m2m().listOrganizationClients("org_123", 20, "");

⚙️ Parameters

organizationId: String - The organization ID

pageSize: int - Page size (between 10 and 100; 0 uses server default)

pageToken: String - Pagination cursor for next page (null or empty string for first page)

Source: View on GitHub →

Last fetched: April 1, 2026