Customize user profiles

Tailor user profiles to your business needs by creating and managing user profile attributes in Scalekit

User profiles in Scalekit provide essential identity information through standard attributes like email, name, and phone number. However, when your application requires business-specific data such as employee IDs, department codes, or access levels, you need more flexibility. T

This guide shows how to extend user profiles with custom attributes that can be created through the dashboard, managed programmatically via API, and synchronized with enterprise identity providers.

Standard user profile attributes

Let’s start by looking at the existing standard attributes in a user_profile from the Scalekit’s Get User API response.

1
{
2
  "id": "usp_96194455173923084",     // Unique user identifier
3
  "first_name": "John",              // User's given name
4
  "last_name": "Doe",                // User's family name
5
  "name": "John Doe",                // Full name for UI display
6
  "locale": "en-US",                 // User's language and region preference
7
  "email_verified": true,            // Whether the email address has been confirmed
8
  "phone_number": "+14155552671",    // Contact phone number
2 collapsed lines
9
  "metadata": { }, // Additional, non-structured user data
10
  "custom_attributes": {} // Business-specific user data
11
}

These attributes are also listed in your Scalekit dashboard. Navigate to Dashboard > User Attributes to see them. Let’s see how we can create a custom attribute.

Create custom attributes

To add a custom attribute

Navigate to Dashboard > User Attributes and click Add Attribute.
Configure the new attribute fields:
- Display name - Human-readable label shown in the dashboard (e.g., “Employee Number”)
- Attribute key - Internal field name for API and SDK access (e.g., employee_id)
The new attribute can be used to attach the new information about the user to their user profile.

1
{
2
  "id": "usp_96194455173923084",     // Unique user identifier
3
  "first_name": "John",              // User's given name
4
  "last_name": "Doe",                // User's family name
5
  "name": "John Doe",                // Full name for UI display
6
  "locale": "en-US",                 // User's language and region preference
7
  "email_verified": true,            // Whether the email address has been confirmed
8
  "phone_number": "+14155552671",    // Contact phone number
9
  "metadata": { }, // Additional, non-structured user data
10
  "custom_attributes": {
11
    "pin_number": "123456"
12
  }
13
}

Custom attributes are user profile extensions that can be precisely configured to meet your application’s unique needs. For example, as a logistics platform, you might define custom attributes to capture critical operational details like delivery ZIP codes, service zones, or fleet vehicle specifications that apply all your users.

Map profile attributes to identity providers

When users authenticate through Single Sign-On (SSO) or join an organization, Scalekit can retrieve and transfer user profile information from the identity provider directly to your application via the ID token during the login completion process.

Administrators can configure attribute mapping from their identity provider by selecting specific user profile attributes. This mapping supports both standard and custom attributes seamlessly.

Modify user profile attributes API

If your application provides a user interface for users to view and modify their profile details directly within the app, the Scalekit API enables seamless profile attribute updates.

1
curl -L -X PATCH '<SCALEKIT_ENVIRONMENT_URL>/api/v1/users/<USER_ID>' \
2
-H 'Content-Type: application/json' \
3
-H 'Authorization: Bearer ...2QA' \
4
-d '{
5
  "user_profile": {
6
    "custom_attributes": {
7
      "zip_code": "90210"
8
    }
9
  }
10
}'

1
// Use case: Update user profile with a custom zip code attribute
2
await scalekit.user.updateUser("<userId>", {
3
  userProfile: {
4
    customAttributes: {
5
      zip_code: "11120",
6
    },
7
    firstName: "John",
8
    lastName: "Doe",
9
    locale: "en-US",
10
    name: "John Michael Doe",
11
    phoneNumber: "+14155552671"
12
  }
13
});

1
# Use case: Update user profile with a custom zip code attribute
2
scalekit.user.update_user(
3
    "<user_id>",
4
    user_profile={
5
        "custom_attributes": {
6
            "zip_code": "11120"
7
        },
8
        "first_name": "John",
9
        "last_name": "Doe",
10
        "locale": "en-US",
11
        "name": "John Michael Doe",
12
        "phone_number": "+14155552671"
13
    }
14
)

1
// Use case: Update user profile with a custom zip code attribute
2
updateUser := &usersv1.UpdateUser{
3
    UserProfile: &usersv1.UpdateUserProfile{
4
        CustomAttributes: map[string]string{
5
            "zip_code": "11120",
6
        },
7
        FirstName:   "John",
8
        LastName:    "Doe",
9
        Locale:      "en-US",
10
        Name:        "John Michael Doe",
11
        PhoneNumber: "+14155552671",
12
    },
13
}
14

15
updatedUser, err := scalekitClient.User().UpdateUser(ctx, "<userId>", updateUser)

1
// Use case: Update user profile with a custom zip code attribute
2
UpdateUser updateUser = UpdateUser.newBuilder()
3
    .setUserProfile(
4
        UpdateUserProfile.newBuilder()
5
            .putCustomAttributes("zip_code", "11120")
6
            .setFirstName("John")
7
            .setLastName("Doe")
8
            .setLocale("en-US")
9
            .setName("John Michael Doe")
10
            .setPhoneNumber("+14155552671")
11
            .build())
12
    .build();
13

14
UpdateUserRequest updateReq = UpdateUserRequest.newBuilder()
15
    .setUser(updateUser)
16
    .build();
17

18
User updatedUser = scalekitClient.users().updateUser("<userId>", updateReq);

Link your system identifiers & metadata

Beyond user profile attributes, you can link your systems with Scalekit to easily map, identify and store more context about organizations and users.

This may be helpful when:

You are migrating from an existing system and need to keep your existing identifiers
You are integrating with multiple platforms and need to maintain data consistency
You need to simplify integration by avoiding complex ID mapping between your systems and Scalekit

Organization external IDs for system integration

External IDs let you identify organizations using your own identifiers instead of Scalekit’s generated IDs. This is essential when migrating from existing systems or integrating with multiple platforms.

Set external IDs during organization creation

Include your system’s identifier when creating organizations to maintain consistent references across your infrastructure.

1
// During user signup or organization creation
2
const organization = await scalekit.organization.create({
3
  display_name: 'Acme Corporation',
4
  external_id: 'CUST-12345-ACME' // Your customer ID in your database
5
});
6

7
console.log('Organization created:', organization.id);
8
console.log('Your ID:', organization.external_id);

1
# During user signup or organization creation
2
organization = scalekit.organization.create({
3
    'display_name': 'Acme Corporation',
4
    'external_id': 'CUST-12345-ACME'  # Your customer ID in your database
5
})
6

7
print(f'Organization created: {organization.id}')
8
print(f'Your ID: {organization.external_id}')

1
// During user signup or organization creation
2
org, err := scalekit.Organization.Create(OrganizationCreateOptions{
3
    DisplayName: "Acme Corporation",
4
    ExternalId:  "CUST-12345-ACME", // Your customer ID in your database
5
})
6

7
if err != nil {
8
    log.Fatal(err)
9
}
10

11
fmt.Printf("Organization created: %s\n", org.Id)
12
fmt.Printf("Your ID: %s\n", org.ExternalId)

1
// During user signup or organization creation
2
Organization organization = scalekit.organization().create(
3
    "Acme Corporation",
4
    "CUST-12345-ACME" // Your customer ID in your database
5
);
6

7
System.out.println("Organization created: " + organization.getId());
8
System.out.println("Your ID: " + organization.getExternalId());

Find organizations using your IDs

Use external IDs to quickly locate organizations when processing webhooks, handling customer support requests, or syncing data between systems.

1
// When processing a webhook or customer update
2
const customerId = 'CUST-12345-ACME'; // From your webhook payload
3

4
const organization = await scalekit.organization.getByExternalId(customerId);
5

6
if (organization) {
7
  console.log('Found organization:', organization.display_name);
8
  // Process organization updates, sync data, etc.
9
}

1
# When processing a webhook or customer update
2
customer_id = 'CUST-12345-ACME'  # From your webhook payload
3

4
organization = scalekit.organization.get_by_external_id(customer_id)
5

6
if organization:
7
    print(f'Found organization: {organization.display_name}')
8
    # Process organization updates, sync data, etc.

1
// When processing a webhook or customer update
2
customerId := "CUST-12345-ACME" // From your webhook payload
3

4
org, err := scalekit.Organization.GetByExternalId(customerId)
5
if err != nil {
6
    log.Printf("Error finding organization: %v", err)
7
    return
8
}
9

10
if org != nil {
11
    fmt.Printf("Found organization: %s\n", org.DisplayName)
12
    // Process organization updates, sync data, etc.
13
}

1
// When processing a webhook or customer update
2
String customerId = "CUST-12345-ACME"; // From your webhook payload
3

4
Organization organization = scalekit.organization().getByExternalId(customerId);
5

6
if (organization != null) {
7
    System.out.println("Found organization: " + organization.getDisplayName());
8
    // Process organization updates, sync data, etc.
9
}

Update external IDs when needed

If your customer IDs change or you need to migrate identifier formats, you can update external IDs for existing organizations.

1
const updatedOrg = await scalekit.organization.update(organizationId, {
2
  external_id: 'NEW-CUST-12345-ACME'
3
});
4

5
console.log('External ID updated:', updatedOrg.external_id);

1
updated_org = scalekit.organization.update(organization_id, {
2
    'external_id': 'NEW-CUST-12345-ACME'
3
})
4

5
print(f'External ID updated: {updated_org.external_id}')

1
updatedOrg, err := scalekit.Organization.Update(organizationId, OrganizationUpdateOptions{
2
    ExternalId: "NEW-CUST-12345-ACME",
3
})
4

5
fmt.Printf("External ID updated: %s\n", updatedOrg.ExternalId)

1
Organization updatedOrg = scalekit.organization().update(organizationId, Map.of(
2
    "external_id", "NEW-CUST-12345-ACME"
3
));
4

5
System.out.println("External ID updated: " + updatedOrg.getExternalId());

User external IDs and metadata

Just as organizations need external identifiers, users often require integration with existing systems. User external IDs and metadata work similarly to organization identifiers, enabling you to link Scalekit users with your CRM, HR systems, and other business applications.

When to use user external IDs and metadata

External IDs link Scalekit users to your existing systems:

Reference users in your database, CRM, or billing system
Maintain consistent user identification across multiple platforms
Enable easy data synchronization and lookups

Metadata stores additional user attributes:

Organizational information (department, location, role level)
Business context (territory, quota, access permissions)
Integration data (external system IDs, custom properties)

Set user external IDs and metadata during user creation

1
// Use case: Create user during system migration or bulk import with existing system references
2
const { user } = await scalekit.user.createUserAndMembership("<organizationId>", {
3
  email: "john.doe@company.com",
4
  externalId: "SALESFORCE-003921",
5
  metadata: {
6
    department: "Sales",
7
    employeeId: "EMP-002",
8
    territory: "West Coast",
9
    quota: 150000,
10
    crmAccountId: "ACC-789",
11
    hubspotContactId: "12345",
12
  },
13
  userProfile: {
14
    firstName: "John",
15
    lastName: "Doe",
16
  },
17
  sendInvitationEmail: true,
18
});

1
# Use case: Create user during system migration or bulk import with existing system references
2
user_response = scalekit.user.create_user_and_membership(
3
    "<organization_id>",
4
    email="john.doe@company.com",
5
    external_id="SALESFORCE-003921",
6
    metadata={
7
        "department": "Sales",
8
        "employee_id": "EMP-002",
9
        "territory": "West Coast",
10
        "quota": 150000,
11
        "crm_account_id": "ACC-789",
12
        "hubspot_contact_id": "12345"
13
    },
14
    user_profile={
15
        "first_name": "John",
16
        "last_name": "Doe"
17
    },
18
    send_invitation_email=True
19
)

1
// Use case: Create user during system migration or bulk import with existing system references
2
newUser := &usersv1.CreateUser{
3
    Email: "john.doe@company.com",
4
    ExternalId: "SALESFORCE-003921",
5
    Metadata: map[string]string{
6
        "department":          "Sales",
7
        "employee_id":         "EMP-002",
8
        "territory":           "West Coast",
9
        "quota":               "150000",
10
        "crm_account_id":      "ACC-789",
11
        "hubspot_contact_id":  "12345",
12
    },
13
    UserProfile: &usersv1.CreateUserProfile{
14
        FirstName: "John",
15
        LastName:  "Doe",
16
    },
17
}
18
userResp, err := scalekitClient.User().CreateUserAndMembership(
19
    ctx,
20
    "<organizationId>",
21
    newUser,
22
    true, // sendInvitationEmail
23
)

1
// Use case: Create user during system migration or bulk import with existing system references
2
CreateUser createUser = CreateUser.newBuilder()
3
    .setEmail("john.doe@company.com")
4
    .setExternalId("SALESFORCE-003921")
5
    .putMetadata("department", "Sales")
6
    .putMetadata("employee_id", "EMP-002")
7
    .putMetadata("territory", "West Coast")
8
    .putMetadata("quota", "150000")
9
    .putMetadata("crm_account_id", "ACC-789")
10
    .putMetadata("hubspot_contact_id", "12345")
11
    .setUserProfile(
12
        CreateUserProfile.newBuilder()
13
            .setFirstName("John")
14
            .setLastName("Doe")
15
            .build())
16
    .build();
17

18
CreateUserAndMembershipRequest createUserReq = CreateUserAndMembershipRequest.newBuilder()
19
    .setUser(createUser)
20
    .setSendInvitationEmail(true)
21
    .build();
22

23
CreateUserAndMembershipResponse userResp = scalekitClient.users()
24
    .createUserAndMembership("<organizationId>", createUserReq);

Update user external IDs and metadata for existing users

1
// Use case: Link user with external systems (CRM, HR) and track custom attributes in a single call
2
const updatedUser = await scalekit.user.updateUser("<userId>", {
3
  externalId: "SALESFORCE-003921",
4
  metadata: {
5
    department: "Sales",
6
    employeeId: "EMP-002",
7
    territory: "West Coast",
8
    quota: 150000,
9
    crmAccountId: "ACC-789",
10
    hubspotContactId: "12345",
11
  },
12
});

1
# Use case: Link user with external systems (CRM, HR) and track custom attributes in a single call
2
updated_user = scalekit.user.update_user(
3
    "<user_id>",
4
    external_id="SALESFORCE-003921",
5
    metadata={
6
        "department": "Sales",
7
        "employee_id": "EMP-002",
8
        "territory": "West Coast",
9
        "quota": 150000,
10
        "crm_account_id": "ACC-789",
11
        "hubspot_contact_id": "12345"
12
    }
13
)

1
// Use case: Link user with external systems (CRM, HR) and track custom attributes in a single call
2
updateUser := &usersv1.UpdateUser{
3
    ExternalId: "SALESFORCE-003921",
4
    Metadata: map[string]string{
5
        "department":          "Sales",
6
        "employee_id":         "EMP-002",
7
        "territory":           "West Coast",
8
        "quota":               "150000",
9
        "crm_account_id":      "ACC-789",
10
        "hubspot_contact_id":  "12345",
11
    },
12
}
13
updatedUser, err := scalekitClient.User().UpdateUser(
14
    ctx,
15
    "<userId>",
16
    updateUser,
17
)

1
// Use case: Link user with external systems (CRM, HR) and track custom attributes in a single call
2
UpdateUser updateUser = UpdateUser.newBuilder()
3
    .setExternalId("SALESFORCE-003921")
4
    .putMetadata("department", "Sales")
5
    .putMetadata("employee_id", "EMP-002")
6
    .putMetadata("territory", "West Coast")
7
    .putMetadata("quota", "150000")
8
    .putMetadata("crm_account_id", "ACC-789")
9
    .putMetadata("hubspot_contact_id", "12345")
10
    .build();
11

12
UpdateUserRequest updateReq = UpdateUserRequest.newBuilder()
13
    .setUser(updateUser)
14
    .build();
15

16
User updatedUser = scalekitClient.users().updateUser("<userId>", updateReq);

Find users by external ID

1
// Use case: Look up Scalekit user when you have your system's user ID
2
const user = await scalekit.user.getUserByExternalId("<organizationId>", "SALESFORCE-003921");
3
console.log(`Found user: ${user.email} with ID: ${user.id}`);

1
# Use case: Look up Scalekit user when you have your system's user ID
2
user = scalekit.user.get_user_by_external_id("<organization_id>", "SALESFORCE-003921")
3
print(f"Found user: {user['email']} with ID: {user['id']}")

1
// Use case: Look up Scalekit user when you have your system's user ID
2
user, err := scalekitClient.User().GetUserByExternalId(
3
    ctx,
4
    "<organizationId>",
5
    "SALESFORCE-003921",
6
)
7
if err != nil {
8
    log.Printf("User not found: %v", err)
9
} else {
10
    fmt.Printf("Found user: %s with ID: %s\n", user.Email, user.Id)
11
}

1
// Use case: Look up Scalekit user when you have your system's user ID
2
try {
3
    GetUserByExternalIdResponse response = scalekitClient.users()
4
        .getUserByExternalId("<organizationId>", "SALESFORCE-003921");
5

6
    User user = response.getUser();
7
    System.out.printf("Found user: %s with ID: %s%n", user.getEmail(), user.getId());
8
} catch (Exception e) {
9
    System.err.println("User not found: " + e.getMessage());
10
}

This integration approach maintains consistent user identity across your system architecture while letting you choose the source of truth for authentication and authorization. Both user and organization external IDs work together to provide complete system integration capabilities.