one-on-one meeting

SCIM API Documentation

Humbol SCIM (System for Cross-domain Identity Management) API allows for real-time employee provisioning from customer’s identity provider.

SCIM API Version: 2.0

SCIM API has been tested to work with these identity providers:

Prerequisites

  • Active contract including SCIM API usage with Humbol Inc
  • At least one admin user in customer’s Humbol organization
  • If you want to assign Humbol users in Entra ID according to your Entra ID groups, it requires MS Entra ID Premium P1 license for that person who does the integration (so just 1 pc is enough). Otherwise you have to select each person separately or import all (you might have some accounts in Entra ID which you don’t want to import to Humbol).
    • You can purchase “Microsoft Entra ID P1” license from here (price in 2023 is 5,1€/month): https://admin.microsoft.com/ (Marketplace -> All Products-> Search all product categories-> “Entra” -> Details)
    • Or if you have already some more expensive license (for example Microsoft 365 Business Premium or Microsoft 365 E3) for all, it should also cover this.

Application roles

Humbol application contains these organization level roles which can be controlled via SCIM API:

Admin

Organization admins can invite and remove users from an organization and create new teams and administer all teams in Humbol. Administrators do not see any details of any interaction or action other than via the normal visibility rules.

External admin

External admins have otherwise same rights as organization admins, but its’s visible from their profile that they are external to the organization.

Member

Members can see the organization structure and all interactions and actions, which have “Organization” visibility and their own teams’ interactions and actions. They can administer those teams which they have a team organizer or team supporter role in.

Light Member

Light members mainly use the system only via pre-authenticated links to access those interactions where they are participants or feedback givers. Pre-authenticated links are delivered by email and are person specific and valid only until the discussion has been marked ready. Light members can be team members (but not organizer or supporter) and can participate into actions, but can’t have goals or be action owners. They can also login to Humbol application if they have MS or Google account which corresponds to their email address. Light members do not see any organization level statistics. They don’t see any organization level actions or interactions if they are not part of that team or participate in the specific action or interaction.

External member

External members can see only those teams from the organization which they are part of, plus actions and interactions where they have been registered as participants. They can administer those teams which they have a team organizer or team supporter role in. External members do not see any organization level statistics. They don’t see any organization level actions, goals or interactions if they are not part of that team or participate in the specific action, goal or interaction.

SSO: OAuth 2.0

Administration of permissions and assigned users

Azure Portal

https://portal.azure.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview

Google Workspace

https://admin.google.com/u/0/ac/owl/list?tab=apps

Permissions required by the application

  • User Profile information
    • Read
    • Needed for fetching user’s name and profile picture
    • Used for all users
  • Calendar
    • Read & write
    • Needed for scheduling and creating calendar events
    • Used only by those who book discussions via Humbol
  • Offline access
    • Needed for 2 way integration for calendar so that you can modify meetings in your calendar and it gets also automatically updated to Humbol
    • Used only by those who book discussions via Humbol
    • Kept only active as long there are meetings booked via Humbol

Taking SCIM API into use

As Humbol admin login into your Humbol organization: https://my.humbol.app/login.

Go to organization’s API settings page: https://my.humbol.app/settings#apis

On the page there is visible your organization SCIM API url. Copy it.

Create SCIM API token and copy the value. NOTE! The token value is not saved anywhere on the Humbol service, so if you lose it, you should create a new one and remove old one.

Go to your identity provider and change Humbol applications provisioning settings to automatic and use the scim api url and token you acquired earlier.

Disable group provisioning and do the user field mapping automatically or manually. These SCIM attributes are always required:

  • userName
  • active
  • name.givenName
  • name.familyName
  • emails[type eq ”work”]
    • one and only one

Note roles[primary eq “True”] is not required: if role is not given, it can be administered inside Humbol by admin user. If you do map it in Entra ID every user must have precisely one role.

Just running SCIM provisioning does not activate any new Humbol user licences: after provisioning has been run you can add imported people to Humbol organization and assign them to teams from Humbol: https://my.humbol.app/organization/members/invite

Supported SCIM API features

Supported Resources: Users with a role

Schema and supported attributes

See description of supported attributes: https://my.humbol.app/api/scim/Schemas

/Schemas API

Supported methods: GET

/Users API

Supported methods: POST and GET

Supported filters: “userName eq” and ”emails[type eq “work”].value eq”

/Users/<id> API

Supported methods: GET, PATCH and DELETE

Error responses

HTTP error codes are used according to SCIM specification. If error happens there should be a json body telling the reason.

Support

Contact: support@humbol.app

Schedule a 15min call

Book call