Work with user profiles

When users authenticate through any method—enterprise SSO, social login, or passwordless—Scalekit normalizes their profile information into a consistent, standardized format. This unified approach eliminates the complexity of handling different data formats from various identity providers.

This guide shows you how to work with user profiles, retrieve profile information, and keep user data current across your application.

Understanding normalized profiles

Different identity providers return user information in varying formats and structures. For example:

Google OAuth might return given_name and family_name
Active Directory could provide givenName and surname
A SAML provider might use firstName and lastName

Scalekit automatically converts all these variations into a standard format, so your application logic remains consistent regardless of how users authenticate.

Scenario: Your application needs to display user names consistently, whether they signed in via Google, Okta SAML, or passwordless email. With Scalekit’s normalization, you always access this data the same way.

Prerequisites

Set up your environment
Section titled “Set up your environment”

Create a Scalekit account and complete the quickstart

Have users authenticating through your application

Install the Scalekit SDK

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>

Configure your API credentials:

1
SCALEKIT_ENVIRONMENT_URL='<YOUR_ENVIRONMENT_URL>'
2
SCALEKIT_CLIENT_ID='<ENVIRONMENT_CLIENT_ID>'
3
SCALEKIT_CLIENT_SECRET='<ENVIRONMENT_CLIENT_SECRET>'

Initialize the Scalekit client:

1
import { Scalekit } from '@scalekit-sdk/node';
2

3
const scalekit = new Scalekit(
4
  process.env.SCALEKIT_ENVIRONMENT_URL,
5
  process.env.SCALEKIT_CLIENT_ID,
6
  process.env.SCALEKIT_CLIENT_SECRET
7
);

Create and access user profile data

User profiles contain both standardized attributes and the original data from identity providers, giving you flexibility in how you use the information.

Create users

Create new users in your organization with profile information and metadata. Users can be created with or without an existing organization membership.

Create user with organization membership

Scenario: Add a new employee to your organization with their profile information and role assignments.

const { user } = await scalekit.user.createUserAndMembership("org_123", {
  email: "user@example.com",
  externalId: "ext_12345a67b89c",
  metadata: {
    department: "engineering",
    location: "nyc-office"
  },
  userProfile: {
    firstName: "John",
    lastName: "Doe",
  },
});

import os
from scalekit import ScalekitClient
from scalekit.v1.users.users_pb2 import CreateUser, CreateUserProfile

scalekit_client = ScalekitClient(
    env_url=os.getenv("SCALEKIT_ENV_URL"),
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
)

user_obj = CreateUser(
    email="user@example.com",
    external_id="ext_12345a67b89c",
    metadata={"department": "engineering", "location": "nyc-office"},
    user_profile=CreateUserProfile(
        first_name="John",
        last_name="Doe"
    )
)
create_resp = scalekit_client.users.create_user_and_membership(organization_id="org_123", user=user_obj)

newUser := &usersv1.CreateUser{
    Email:      "user@example.com",
    ExternalId: "ext_12345a67b89c",
    Metadata: map[string]string{
        "department": "engineering",
        "location":   "nyc-office",
    },
    UserProfile: &usersv1.CreateUserProfile{
        FirstName: "John",
        LastName:  "Doe",
    },
}
cuResp, err := sc.User().CreateUserAndMembership(ctx, "org_123", newUser, false)
if err != nil { /* handle error */ }

CreateUser createUser = CreateUser.newBuilder()
    .setEmail("user@example.com")
    .setExternalId("ext_12345a67b89c")
    .putMetadata("department", "engineering")
    .putMetadata("location", "nyc-office")
    .setUserProfile(
        CreateUserProfile.newBuilder()
            .setFirstName("John")
            .setLastName("Doe")
            .build())
    .build();

CreateUserAndMembershipRequest cuReq = CreateUserAndMembershipRequest.newBuilder()
    .setUser(createUser)
    .build();

CreateUserAndMembershipResponse cuResp = users.createUserAndMembership("org_123", cuReq);
System.out.println(cuResp.getUser().getId());

curl 'https://$SCALEKIT_ENVIRONMENT_URL/api/v1/organizations/{organization_id}/users' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "user@example.com",
  "external_id": "ext_12345a67b89c",
  "membership": {
    "metadata": {
      "department": "engineering",
      "location": "nyc-office"
    },
    "roles": "admin"
  },
  "metadata": {
    "department": "engineering",
    "location": "nyc-office"
  },
  "user_profile": {
    "custom_attributes": {
      "department": "engineering",
      "security_clearance": "level2"
    },
    "first_name": "John",
    "last_name": "Doe",
    "locale": "en-US",
    "metadata": {
      "account_status": "active",
      "signup_source": "mobile_app"
    },
    "name": "John Michael Doe",
    "phone_number": "+14155552671"
  }
}'

Most B2B applications create organizations or workspaces to group users together. You’ll need to create an organization first before adding users to it by passing organization_id to the createUserAndMembership method.

Explore Organization APIs →

Get user profile information

Scenario: Display a user’s profile information in your application’s settings page or admin dashboard.

const { user } = await scalekit.user.getUser("usr_456");

response = scalekit_client.users.get_user(user_id="usr_456")
user = response[0].user

resp, err := sc.User().GetUser(ctx, "usr_456")
if err != nil { log.Fatal(err) }
user := resp.User

GetUserResponse resp = scalekit.users().getUser("usr_456");
var user = resp.getUser();

Update user profiles

Users need to keep their profile information current, and administrators may need to update user details for compliance or organizational changes.

Update user information

Scenario: An organization administrator needs to update a user’s department after an internal transfer.

1
const updatedUser = await scalekit.user.updateUser("usr_456", {
2
  userProfile: {
3
    firstName: "Jane",
4
    lastName: "Smith", // Updated after marriage
5
  },
6
  metadata: {
7
    department: "Product",            // Transferred departments
8
    role: "Senior Developer",
9
    lastUpdated: new Date().toISOString(),
10
    manager: "john.doe@example.com",
11
  },
12
});
13

14
console.log("User profile updated:", updatedUser.id);

1
from datetime import datetime
2
from scalekit.v1.users.users_pb2 import UpdateUser, UpdateUserProfile
3

4
update_user = UpdateUser(
5
    user_profile=UpdateUserProfile(
6
        first_name="Jane",
7
        last_name="Smith",
8
    ),
9
    metadata={
10
        "department": "Product",
11
        "role": "Senior Developer",
12
        "manager": "john.doe@example.com",
13
        "lastUpdated": datetime.utcnow().isoformat(),
14
    },
15
)
16

17
response = scalekit_client.users.update_user(user_id="usr_456", user=update_user)
18
print("User profile updated!")

1
upd := &usersv1.UpdateUser{
2
    UserProfile: &usersv1.UpdateUserProfile{
3
        FirstName: "Jane",
4
        LastName:  "Smith",
5
    },
6
    Metadata: map[string]string{
7
        "department": "Product",
8
        "role":       "Senior Developer",
9
        "manager":    "john.doe@example.com",
10
    },
11
}
12

13
resp, err := sc.User().UpdateUser(ctx, "usr_456", upd)
14
if err != nil {
15
    log.Fatalf("update user: %v", err)
16
}
17
fmt.Println("User profile updated:", resp.User.Id)

1
UpdateUser upd = UpdateUser.newBuilder()
2
    .setUserProfile(UpdateUserProfile.newBuilder()
3
        .setFirstName("Jane")
4
        .setLastName("Smith")
5
        .build())
6
    .putMetadata("department", "Product")
7
    .putMetadata("role", "Senior Developer")
8
    .putMetadata("manager", "john.doe@example.com")
9
    .build();
10

11
UpdateUserResponse res = users.updateUser(
12
    "usr_456",
13
    UpdateUserRequest.newBuilder().setUser(upd).build()
14
);
15
System.out.println("User profile updated: " + res.getUser().getId());

Update user metadata

Scenario: Store application-specific information like user preferences, billing details, or custom attributes that enhance your user experience.

1
const updatedUser = await scalekit.user.updateUser("usr_456", {
2
  metadata: {
3
    theme: "dark",
4
    timezone: "America/New_York",
5
    notificationPreferences: {
6
      email: true,
7
      slack: false,
8
      mobile: true,
9
    },
10
    lastLoginAt: new Date().toISOString(),
11
  },
12
});
13

14
console.log("User metadata updated");

1
from datetime import datetime
2
from scalekit.v1.users.users_pb2 import UpdateUser
3

4
update_user = UpdateUser(
5
    metadata={
6
        "theme": "dark",
7
        "timezone": "America/New_York",
8
        "notificationPreferences": {
9
            "email": True,
10
            "slack": False,
11
            "mobile": True,
12
        },
13
        "lastLoginAt": datetime.utcnow().isoformat(),
14
    },
15
)
16

17
response = scalekit_client.users.update_user(user_id="usr_456", user=update_user)
18
print("User metadata updated")

1
upd := &usersv1.UpdateUser{
2
    Metadata: map[string]string{
3
        "theme":      "dark",
4
        "timezone":   "America/New_York",
5
        "lastLoginAt": time.Now().Format(time.RFC3339),
6
    },
7
}
8

9
if _, err := sc.User().UpdateUser(ctx, "usr_456", upd); err != nil {
10
    log.Fatalf("update metadata: %v", err)
11
}
12
fmt.Println("User metadata updated")

1
UpdateUser upd = UpdateUser.newBuilder()
2
    .putMetadata("theme", "dark")
3
    .putMetadata("timezone", "America/New_York")
4
    .putMetadata("lastLoginAt", Instant.now().toString())
5
    .build();
6

7
users.updateUser(
8
    "usr_456",
9
    UpdateUserRequest.newBuilder().setUser(upd).build()
10
);
11
System.out.println("User metadata updated");

User profile structure

Understanding the normalized profile structure helps you work with user data effectively across different authentication methods.

1
{
2
  "user": {
3
    "id": "usr_1234abcd5678efgh",
4
    "email": "john.doe@acmecorp.com",
5
    "external_id": "ext_12345a67b89c",
6
    "create_time": "2025-06-24T12:15:33.784Z",
7
    "update_time": "2025-06-24T12:15:33.784Z",
8
    "last_login": "2025-06-24T12:15:33.784Z",
9
    "user_profile": {
10
      "id": "usr_profile_1234abcd5678efgh",
11
      "name": "John Michael Doe",
12
      "first_name": "John",
13
      "last_name": "Doe",
14
      "phone_number": "+14155552671",
15
      "email_verified": true,
16
      "locale": "en-US",
17
      "custom_attributes": {
18
        "department": "engineering",
19
        "security_clearance": "level2"
20
      },
21
      "metadata": {
22
        "account_status": "active",
23
        "signup_source": "mobile_app"
24
      }
25
    },
26
    "metadata": {
27
      "department": "engineering",
28
      "location": "nyc-office"
29
    },
30
    "memberships": [
31
      {
32
        "organization_id": "org_1234abcd5678efgh",
33
        "name": "Acme Corp",
34
        "join_time": "2025-06-24T12:15:33.784Z",
35
        "membership_status": "ACTIVE",
36
        "primary_identity_provider": "OKTA",
37
        "metadata": {
38
          "department": "engineering",
39
          "location": "nyc-office"
40
        },
41
        "roles": [
42
          {
43
            "id": "role_123",
44
            "name": "Developer"
45
          }
46
        ]
47
      }
48
    ]
49
  }
50
}

Standard profile attributes

Attribute	Data type	Description
`id`	string	Unique identifier for the user
`email`	string	The user’s email address
`external_id`	string	External identifier for the user
`create_time`	string	ISO 8601 timestamp when the user was created
`update_time`	string	ISO 8601 timestamp when the user was last updated
`last_login`	string	ISO 8601 timestamp of the user’s last login
`user_profile.name`	string	Full formatted name combining first and last name
`user_profile.first_name`	string	The user’s first name or given name
`user_profile.last_name`	string	The user’s last name or surname
`user_profile.phone_number`	string	The user’s phone number
`user_profile.email_verified`	boolean	Whether the email address has been verified
`user_profile.locale`	string	User’s locale as a BCP 47 language tag (e.g., ‘en-US’, ‘fr’)
`user_profile.custom_attributes`	object	Custom attributes specific to the user profile
`user_profile.metadata`	object	Metadata specific to the user profile
`metadata`	object	Custom key-value data specific to your application

Membership information

The memberships array contains information about the user’s organizational memberships and roles.

Membership attribute	Data type	Description
`organization_id`	string	Unique identifier for the organization
`name`	string	Name of the organization
`join_time`	string	ISO 8601 timestamp when the user joined the organization
`membership_status`	string	Status of the membership (e.g., “ACTIVE”, “INACTIVE”)
`primary_identity_provider`	string	Primary identity provider for this membership
`metadata`	object	Organization-specific metadata for the user
`roles`	array	Array of role objects with `id` and `name` properties

Now that you understand user profiles, explore related topics:

Manage users to learn about creating and managing user accounts
Configure user roles to define permissions and access control
Implement sign-up to understand how profiles are created during registration