Create and manage organizations

Organizations are the foundation of your B2B application, representing your customers and their teams. In Scalekit, organizations serve as multi-tenant containers that isolate user data, configure authentication methods, and manage enterprise features like Single Sign-On (SSO) and directory synchronization.

This guide shows you how to create and manage organizations programmatically and through the Scalekit dashboard.

Understanding organizations

Users can belong to multiple organizations with the same identity. This is common in products like Notion, where users collaborate across multiple workspaces.

Create an organization

Organizations can be created automatically during user sign-up or programmatically through the API. When users sign up for your application, Scalekit creates a new organization and adds the user to it automatically.

For more control over the organization creation process, create organizations programmatically:

npm install @scalekit-sdk/node

pip install scalekit-sdk-python

go get -u github.com/scalekit-inc/scalekit-sdk-go

/* Gradle users - add the following to your dependencies in build file */
implementation "com.scalekit:scalekit-sdk-java:1.1.3"

<!-- Maven users - add the following to your `pom.xml` -->
<dependency>
    <groupId>com.scalekit</groupId>
    <artifactId>scalekit-sdk-java</artifactId>
    <version>1.1.3</version>
</dependency>

1
const organization = await scalekit.organization.createOrganization('Acme Corporation', {
2
  externalId: 'acme-corp-123',
3
  metadata: {
4
    plan: 'enterprise',
5
    industry: 'technology'
6
  }
7
});
8

9
console.log('Organization created:', organization.id);

1
from scalekit.v1.organizations.organizations_pb2 import CreateOrganization
2

3
organization = scalekit_client.organization.create_organization(
4
    CreateOrganization(
5
        display_name='Acme Corporation',
6
        external_id='acme-corp-123',
7
        metadata={
8
            'plan': 'enterprise',
9
            'industry': 'technology'
10
        }
11
    )
12
)
13

14
print(f'Organization created: {organization.id}')

1
organization, err := scalekitClient.Organization.CreateOrganization(
2
    ctx,
3
    "Acme Corporation",
4
    scalekit.CreateOrganizationOptions{
5
        ExternalId: "acme-corp-123",
6
        Metadata: map[string]interface{}{
7
            "plan": "enterprise",
8
            "industry": "technology",
9
        },
10
    },
11
)
12
if err != nil {
13
    log.Fatal(err)
14
}
15

16
fmt.Printf("Organization created: %s\n", organization.ID)

1
import java.util.Map;
2
import java.util.HashMap;
3

4
Map<String, Object> metadata = new HashMap<>();
5
metadata.put("plan", "enterprise");
6
metadata.put("industry", "technology");
7

8
CreateOrganization createOrg = CreateOrganization.newBuilder()
9
    .setDisplayName("Acme Corporation")
10
    .setExternalId("acme-corp-123")
11
    .putAllMetadata(metadata)
12
    .build();
13

14
Organization organization = scalekitClient.getOrganization().create(createOrg);
15
System.out.println("Organization created: " + organization.getId());

External ID: An optional field to associate the organization with an ID from your system. This is useful for linking Scalekit organizations with records in your own database.

Update organization details

Organization administrators often need to make changes after the initial setup. Typical examples include:

Renaming the organization after a corporate re-brand.
Uploading or replacing the company logo shown on your dashboard or invoices.
Storing metadata your application needs at runtime—such as a billing plan identifier, Stripe customer ID, or internal account reference.

1
const updatedOrganization = await scalekit.organization.updateOrganization(
2
  'org_12345',
3
  {
4
    displayName: 'Acme Corporation Ltd',
5
    metadata: {
6
      plan: 'enterprise',
7
      paymentMethod: 'stripe',
8
      customField: 'custom-value'
9
    }
10
  }
11
);

1
updated_organization = scalekit_client.organization.update_organization(
2
    organization_id='org_12345',
3
    organization= UpdateOrganization(
4
            display_name='Acme Corporation Ltd',
5
            metadata={
6
                'plan': 'enterprise',
7
                'payment_method': 'stripe',
8
                'custom_field': 'custom-value'
9
            }
10
        )
11
)

1
metadata := map[string]interface{}{
2
    "plan": "enterprise",
3
    "payment_method": "stripe",
4
    "custom_field": "custom-value",
5
}
6

7
updatedOrganization, err := scalekitClient.Organization.UpdateOrganization(
8
    ctx,
9
    "org_12345",
10
    scalekit.UpdateOrganizationOptions{
11
        DisplayName: "Acme Corporation Ltd",
12
        Metadata: metadata,
13
    },
14
)

1
Map<String, Object> metadata = new HashMap<>();
2
metadata.put("plan", "enterprise");
3
metadata.put("payment_method", "stripe");
4
metadata.put("custom_field", "custom-value");
5

6
Organization updatedOrganization = scalekitClient.getOrganization()
7
    .updateOrganization("org_12345", UpdateOrganizationRequest.builder()
8
        .displayName("Acme Corporation Ltd")
9
        .metadata(metadata)
10
        .build());

Metadata: Store additional information about the organization, such as subscription plans, payment methods, or any custom data relevant to your application.

Configure organization features

Enable enterprise features for your organizations to support authentication methods like SSO and user provisioning through SCIM.

1
const settings = {
2
  features: [
3
    {
4
      name: 'sso',
5
      enabled: true,
6
    },
7
    {
8
      name: 'dir_sync',
9
      enabled: true,
10
    },
11
  ],
12
};
13

14
await scalekit.organization.updateOrganizationSettings(
15
  'org_12345',
16
  settings
17
);

1
settings = {
2
    "features": [
3
        {"name": "sso", "enabled": True},
4
        {"name": "dir_sync", "enabled": True}
5
    ]
6
}
7

8
scalekit_client.organization.update_organization_settings(
9
    'org_12345',
10
    settings
11
)

1
settings := map[string]interface{}{
2
    "features": []map[string]interface{}{
3
        {"name": "sso", "enabled": true},
4
        {"name": "dir_sync", "enabled": true},
5
    },
6
}
7

8
err := scalekitClient.Organization.UpdateOrganizationSettings(
9
    ctx,
10
    "org_12345",
11
    settings
12
)

1
Map<String, Object> settings = new HashMap<>();
2
settings.put("features", Arrays.asList(
3
    new HashMap<String, Object>() {{
4
        put("name", "sso");
5
        put("enabled", true);
6
    }},
7
    new HashMap<String, Object>() {{
8
        put("name", "dir_sync");
9
        put("enabled", true);
10
    }}
11
));
12

13
scalekitClient.getOrganization().updateOrganizationSettings(
14
    "org_12345",
15
    settings
16
);

Admin Portal access (self-serve configuration)

Enterprise customers usually want to manage SSO and directory sync on their own, without involving your support team. Scalekit provides an Admin Portal that you can surface to IT administrators in two ways:

Generate a shareable link and send it via email or chat.
Embed the portal inside your own settings page with an <iframe>.

Both approaches give administrators a sandboxed interface to configure SSO (SAML/OIDC) connections, SCIM provisioning, and other security settings.

1
const portalLink = await scalekit.organization.generatePortalLink('org_12345');
2

3
// Present this URL to the organization's IT admin or load it in an iframe
4
console.log('Admin Portal URL:', portalLink.url);

1
portal_link = scalekit_client.organization.generate_portal_link('org_12345')
2
print(f'Admin Portal URL: {portal_link.url}')

1
portalLink, err := scalekitClient.Organization.GeneratePortalLink(ctx, "org_12345")
2
if err != nil {
3
    log.Fatal(err)
4
}
5
fmt.Println("Admin Portal URL:", portalLink.URL)

1
PortalLink portalLink = scalekitClient.getOrganization().generatePortalLink("org_12345");
2
System.out.println("Admin Portal URL: " + portalLink.getUrl());

For advanced customization options, see the Admin Portal guide.

Configure SSO and SCIM from the dashboard

As an alternative to the Admin Portal, you can configure SSO and SCIM directly from the Scalekit dashboard. This approach is useful when you want to set up these features for your customers without sharing admin portal access.

Set up SSO configuration

Configure Single Sign-On to connect your customer’s identity provider with Scalekit. From the organization’s settings page in the dashboard, you can set up SSO connections.

To configure SSO:

Configure user attributes by mapping attributes from the identity provider to user profiles in Scalekit.
Enter identity provider configuration with metadata from your customer’s IdP, including Entity ID, ACS URL, and X.509 certificate.
Assign users and groups to specify which users and groups can use this SSO connection.
Test SSO by performing a test login to ensure the connection works correctly.
Enable connection once you’ve verified the configuration is working.

For step-by-step guides on configuring specific identity providers, see SSO integrations.

Set up SCIM configuration

Configure SCIM provisioning to allow your customers to provision and manage users and groups automatically from their directory provider.

To set up SCIM:

Generate SCIM endpoint and provide this URL to your customer for configuration in their directory provider.
Create bearer token and share this rotatable token with your customer for secure authentication.
Monitor synced users and groups to verify which users and groups are being synced after the connection is active.

For detailed configuration guides with specific providers, see SCIM integrations to automate user and group management.

Group-based role assignment Learn how to assign roles to users based on their group memberships from the directory provider.

Organization specific policies

Configure advanced authentication and access control policies to meet your organization’s security requirements.

Authentication methods Coming soon

Organization admins will be able to configure which authentication methods are available to their organization members. For example, they can restrict access to only enterprise SSO for enhanced security, or allow a combination of SSO and passwordless authentication for flexible user access.

Session settings Coming soon

Organization admins will be able to configure session settings for all their organization members. They can set session timeout, idle timeout, and other session-related settings that align with their organization’s security policies and compliance requirements.

What’s next?

Manage users to create, update, and delete user accounts within organizations
Enable Enterprise SSO to configure single sign-on for your customers
Set up SCIM provisioning to automate user and group management