Overview

Endpoints related to user administration require the Administrator role and the CompanyKey header.

Inviting a User

Available API endpoints related to user invite can be found here: https://developer.unimicro.no/docs/UserVerification

Endpoint

POST api/biz/user-verifications

Request Body

{ 
  "Email": "string", 
  "UserType": null 
}

Requires: CompanyKey header.

Set UserType to null when inviting a standard user.

Behavior

• If the email already belongs to a user in the identity server:
  • The user is automatically added and activated.
  • A notification is sent via email.
• If the email is new:
  • An invite is sent via email.
• The user will automatically purchase all default products on the contract type of the company.
• The user is assigned all default roles associated with these products.

Modifying User Access

Important Considerations About User Roles

• All roles (except for a few, like Administrator) require at least one active purchase of a product that allows the role.
• Allowed roles are defined in the product's ListOfRoles property (comma-separated string of role names).
• Products also have a DefaultRoles property, listing roles automatically assigned upon purchase.
• Accountants and support users are exempt from this rule, as they do not purchase products.

Fetching User Details

To modify user purchases and roles, first, fetch the user details:

GET api/biz/users?filter=Email eq '{user_email}'

Requires: CompanyKey header.

This request should return a single user entry since email is unique per company.

You need the User ID and GlobalIdentity to proceed with modifications.

Fetching Available Products

Fetch products from the license server:

GET {License Server URL}/api/contracttypes/{contract_type}/products?$filter=isperuser eq true and productstatus eq 'Live' and producttype in ('Module', 'Package')&$select=id,label,name,listofroles,defaultroles,producttype,productstatus,ismandatoryproduct,isdefaultproduct,isperuser

Requires: CompanyKey header.

Fetching Roles and User Roles

To modify user access, retrieve the existing roles and assigned roles:

Fetch All Roles

GET api/biz/roles

Requires: CompanyKey header.

Fetch User Roles

GET api/biz/userroles?filter=UserID eq {user.ID}

Requires: CompanyKey header.

Fetching Purchases for the User

Retrieve all company purchases:

GET api/elsa/purchases

Requires: CompanyKey header.

Filter the results based on GlobalIdentity to ensure you are working with the correct user:

purchase.GlobalIdentity === user.GlobalIdentity

This provides all the data required for modifying purchases and roles.

Managing User Roles

Adding Roles

POST api/biz/userroles?action=bulk-insert-roles

Request Body

[ 
  { 
    "SharedRoleId": "role.ID", 
    "SharedRoleName": "role.Name", 
    "UserID": "user.ID" 
  } 
]

Requires: CompanyKey header.

This endpoint accepts an array of roles, allowing multiple roles to be assigned at once.

Removing Roles

DELETE api/biz/userroles?action=bulk-delete-roles&userRoleIds=15,76,83

Requires: CompanyKey header.

• userRoleIds is a comma-separated list of UserRole.IDs to be removed.
• Since roles grant access to system areas, removing all roles for a purchased product may result in the user losing functionality.
• As a courtesy, consider manually deleting the purchase if all roles tied to it are removed, ensuring users are not billed for an unusable product.

Alternative: Adding an Existing User to a company via GlobalIdentity

If the GlobalIdentity of the user is known, an alternative approach can be used.

POST api/biz/users?action=add-user&globalIdentity={user.GlobalIdentity}

Request Body

null

Requires: CompanyKey header.

Notes:

• This will fail if the user does not exist in the identity server.
• It functions similarly to POST user-verification, but does not send an email notification.

Bulk Update Permissions

Endpoint Overview

This endpoint allows an authenticated LicenseAdmin user to update (or add) permissions for multiple users across one or more companies in a single bulk operation. This endpoint creates servicebus messages, which are queued for processing by Unimicro License and further update the permissions.

URL and HTTP Method

POST https://byra.unimicro.no/api/companies/v2/update-permissions

API Version: v2 HTTP Method: POST

Request Headers

• Content-Type: application/json
• Authorization: A valid bearer token is required. The endpoint verifies that the requesting user is a LicenseAdmin.

Request Body

{ 
  "CompanyIds": [1, 2, 3], 
  "UserIds": [101, 102, 103], 
  "Roles": ["Admin", "Accounting.Admin", "Sales.Manager"] 
}

Request Fields

YesArray of role names to be applied to specified users. If null, no role change occurs.

Security and Authorization

License Administration Check

Failure: Status Code: 403 Forbidden Response:

{ 
  "Message": "No permission to add user to companies" 
}

Company-Level Permission Check

For each company provided, the system checks if the user holds either:

• License Permission (if the user has a valid license permission for the company with role 1 or 2).
• Purchase Permission (if an agency purchase permission record exists).

Failure Response:

{ 
  "Message": "No permission to admin license for company {companyId}" 
}

Response

Success Response

Status Code: 200 OK

Error Responses

Conclusion

This guide covers inviting users and modifying their access. Managing product purchases for users will be discussed in a separate article.

For further details, refer to the API documentation or reach out to the Unimicro development team.