Account Attributes

Each account in Visma Connect IdP has two key attributes that are unique at any given time:

UserID

A unique identifier assigned to a user account in the form of a UUID (Universal Unique Identifier).
This value is immutable and remains the same for the lifetime of the account.

Example: a6cd749d-143e-4c42-8266-f99aaa225c2e

Email

An email address is unique across all accounts in the system at any given time.
However, an email can be changed multiple times, meaning it may be associated with different accounts over time.
The email address is used for signing in, serving as the primary credential along with the password.

Example: john.doe@example.org

Shared Accounts Across Visma Applications

Accounts in Visma Connect IdP are shared across all Visma applications and business units. Any Visma application can update the email address of an account at any time.

Linking Accounts: Use UserID, Not Email

Since the email value can change over time, integrated applications must store and reference the immutable Visma Connect UserID instead of the email address when linking accounts.

For example, a Visma HRM system should link:

Visma Connect UserID: a6cd749d-143e-4c42-8266-f99aaa225c2e
Visma HRM UserID: 12450

This linkage is typically done when provisioning the account using the Connect Public API (e.g., via the "Add User" method).

Matching Accounts After Successful Sign-In

After a user signs in via Visma Connect, the application will receive an Access Token (JWT format), which contains the Visma Connect UserID in the sub (subject) attribute.

Applications must match the signed-in UserID with their internal user account ID to ensure the correct account and data are accessed.

Important
Email should never be used for matching, as it can change over time. Relying on email matching may lead to unauthorized access to the wrong account if systems are not synchronized.

Updating Account Information During Sign-In

Applications should retrieve updated user information by calling the Userinfo /connect/userinfo endpoint using the Access Token. This provides:

Email
First Name
Last Name

A Just-in-Time (JIT) update should be performed on each sign-in to synchronize user data with the application’s internal system.

Webhook Sync for Real-Time Updates

Applications should subscribe to Webhook events from Visma Connect IdP to receive real-time notifications whenever an account is updated, specifically the USERACCOUNT_MODIFIED event.

You setup a Webhook subscription for your App in the Developer Portal.

{
   "event":"USERACCOUNT_MODIFIED",
   "event_date":"2024-12-31T13:15:30Z",
   "user_id":"a6cd749d-143e-4c42-8266-f99aaa225c2e",
   "payload":{
      "old_values":{
         "first_name":"John",
         "last_name":"Doe",
         "country_code":"NO",
         "preferred_language":"en-GB",
         "email":"john.doe@example.com",
         "email_verified":true,
         "phone_number":"+47999999",
         "phone_verified":false
      },
      "current_values":{
         "first_name":"John",
         "last_name":"Doe",
         "country_code":"NO",
         "preferred_language":"en-GB",
         "email":"johnny.doe@example.org",
         "email_verified":true,
         "phone_number":"+47999999",
         "phone_verified":false
      },
      "modified_attributes":[
         "email"
      ],
      "application_id":"accountsettings"
   }
}

Best Practices for Webhook Sync:

Use the Connect UserID to update corresponding user details (email, first name, last name) in your Application.
Never rely on email for user identification since it may be out of sync.

For example, if a webhook event is received for:

Visma Connect UserID: a6cd749d-143e-4c42-8266-f99aaa225c2e
Update should be applied to Visma HRM UserID: 12450, not based on email.

Documentation Index