Create organizations

An Organization enables shared data access and enforces consistent authentication methods, session policies, and access control policies for all its members. Scalekit supports two main approaches to organization creation:

1. Sign up creates organizations automatically: When users successfully authenticate with your app, Scalekit automatically creates an organization for them.
2. User creates organizations themselves: When your application provides users with the option to create new organizations themselves. For instance, Jira enables users to create their own workspaces.

Sign up creates organizations automatically

Existing Scalekit integration to authenticate users and handle the login flow automatically generates an organization for each user. The organization ID associated with the user will be included in both the ID token and access token.

Decoded ID token

ID token decoded

{
  "at_hash": "ec_jU2ZKpFelCKLTRWiRsg", // Access token hash for validation
12 collapsed lines
  "aud": [
    "skc_58327482062864390" // Audience (your client ID)
  ],
  "azp": "skc_58327482062864390", // Authorized party (your client ID)
  "c_hash": "6wMreK9kWQQY6O5R0CiiYg", // Authorization code hash
  "client_id": "skc_58327482062864390", // Your application's client ID
  "email": "john.doe@example.com", // User's email address
  "email_verified": true, // Whether the user's email is verified
  "exp": 1742975822, // Expiration time (Unix timestamp)
  "family_name": "Doe", // User's last name
  "given_name": "John", // User's first name
  "iat": 1742974022, // Issued at time (Unix timestamp)
  "iss": "https://scalekit-z44iroqaaada-dev.scalekit.cloud", // Issuer (Scalekit environment URL)
  "name": "John Doe", // User's full name
  "oid": "org_59615193906282635", // Organization ID
  "sid": "ses_65274187031249433", // Session ID
  "sub": "usr_63261014140912135" // Subject (user's unique ID)
}

Decoded access token

Decoded access token

{
    "aud": [
      "prd_skc_7848964512134X699" // Audience (API or resource server)
    ],
    "client_id": "prd_skc_7848964512134X699", // Your application's client ID
    "oid": "org_89678001X21929734", // Organization ID
    "exp": 1758265247, // Expiration time (Unix timestamp)
    "iat": 1758264947, // Issued at time (Unix timestamp)
10 collapsed lines
    "iss": "https://login.devramp.ai", // Issuer (Scalekit environment URL)
    "jti": "tkn_90928731115292X63", // JWT ID (unique token identifier)
    "nbf": 1758264947, // Not before time (Unix timestamp)
    "permissions": [ // Scopes or permissions granted
      "workspace_data:write",
      "workspace_data:read"
    ],
    "roles": [ // User roles within the organization
      "admin"
    ],
    "sid": "ses_90928729571723X24", // Session ID
    "sub": "usr_8967800122X995270", // Subject (user's unique ID)
}

Allow users to create organizations API

Applications often provide options for users to create their own organizations.

For example, show an option for users such “Create new workspace” within their app. Use the Scalekit SDK to power such options:

Node.js

Create and manage organizations

const { organization } = await scalekit.organization.createOrganization(
  'Orion Analytics'
);

// Use case: Sync organization profile to downstream systems
const { organization: fetched } = await scalekit.organization.getOrganization(organization.id);

Python

Create and manage organizations

from scalekit.v1.organizations.organizations_pb2 import CreateOrganization

response = scalekit_client.organization.create_organization(
    CreateOrganization(
        display_name="Orion Analytics",
    )
)

# Use case: Sync organization profile to downstream systems
fetched = scalekit_client.organization.get_organization(response[0].organization.id)

Go

Create and manage organizations

created, err := scalekitClient.Organization().CreateOrganization(
    ctx,
    "Orion Analytics",
    scalekit.CreateOrganizationOptions{},
)
if err != nil {
    log.Fatalf("create organization: %v", err)
}

// Use case: Sync organization profile to downstream systems
fetched, err := scalekitClient.Organization().GetOrganization(ctx, created.Organization.Id)
if err != nil {
    log.Fatalf("get organization: %v", err)
}

Java

Create and manage organizations

// Use case: Provision a workspace after a sales-assisted onboarding
CreateOrganization createOrganization = CreateOrganization.newBuilder()
    .setDisplayName("Orion Analytics")
    .build();

Organization organization = scalekitClient.organizations().create(createOrganization);

// Use case: Sync organization profile to downstream systems
Organization fetched = scalekitClient.organizations().getById(organization.getId());

Set organization properties at creation

Pass additional properties when you create an organization to give it a slug, map it to your own system, or brand its hosted pages. Every property except the display name is optional.

Property	Description
display_name	Human-readable name shown in the dashboard and hosted UI. Required.
slug	DNS-safe identifier such as orion or auth.orion-analytics.com. Expands {{org_slug}} in template redirect URLs.
external_id	Your own identifier for the organization, so you can look it up by your system’s ID.
logo_url	Publicly accessible logo URL shown on branded login pages and portals.

Node.js

Create an organization with properties

const { organization } = await scalekit.organization.createOrganization(
  'Orion Analytics',
  {
    slug: 'orion',
    externalId: 'customer_12345',
    logoUrl: 'https://cdn.orion-analytics.com/logo.png',
  }
);

Python

Create an organization with properties

from scalekit.v1.organizations.organizations_pb2 import CreateOrganization

response = scalekit_client.organization.create_organization(
    CreateOrganization(
        display_name="Orion Analytics",
        slug="orion",
        external_id="customer_12345",
        logo_url="https://cdn.orion-analytics.com/logo.png",
    )
)

Go

Create an organization with properties

slug := "orion"
externalID := "customer_12345"
logoURL := "https://cdn.orion-analytics.com/logo.png"

created, err := scalekitClient.Organization().CreateOrganization(
    ctx,
    "Orion Analytics",
    scalekit.CreateOrganizationOptions{
        Slug:       &slug,
        ExternalId: &externalID,
        LogoUrl:    &logoURL,
    },
)
if err != nil {
    log.Fatalf("create organization: %v", err)
}

Java

Create an organization with properties

CreateOrganization createOrganization = CreateOrganization.newBuilder()
    .setDisplayName("Orion Analytics")
    .setSlug("orion")
    .setExternalId("customer_12345")
    .setLogoUrl("https://cdn.orion-analytics.com/logo.png")
    .build();

Organization organization = scalekitClient.organizations().create(createOrganization);

Set a slug for friendly redirect URLs

A slug gives each organization a DNS-safe identifier that expands {{org_slug}} in template redirect URLs. You can also set or change it later with updateOrganization.

Next, let’s look at how users can be added to organizations.