Set up SCIM for your app

​

Prerequisites

• Single sign-on (SSO) must be enabled in your HubSpot account.
• It’s recommended to set up user permission sets in HubSpot based on your team’s IdP Roles before setting up SCIM. Your IdP can then assign permissions to a user if their roles in the IdP matches the name of the HubSpot permission set.
• To verify your domain, you will need to update your DNS records. Ensure you have the login details for your DNS provider and have access to the TXT records.
• Assigning seats will vary depending on whether or not you’re on the seats-based pricing model:
  • If you are not on a seats-based pricing model: to assign paid seats for users set up with SCIM, purchase the seats in HubSpot and create a permission set with a paid seat. Navigate back to your IdP and set the user’s Roles to be the same as the permission set.
  • If you are using the seats-based pricing model: you cannot assign seats such as core seats, Sales or Service Hub seats, or view-only seats, based on permission sets assigned in your IdP. Before assigning permissions through your IdP, you will need to update a user’s seat in HubSpot.

​

Limitations and user syncing

• Only user permissions can be edited in HubSpot, and only if permission set management is not configured. All other user information, including name and email address, can only be updated through your identity provider.
• To sync identity provider roles with HubSpot permission sets, turn on permission set management in HubSpot. The permission set name in HubSpot must match the exact role name in your identity provider, including any space characters and capital letters.
• Your identity provider can’t automatically assign users to teams, but after the user is added, you can update their team manually in HubSpot.
• Deleting a user in HubSpot will not delete the user in your identity provider. However, if you remove a user’s access to HubSpot from your identity provider, or deactivate the user in your identity provider, the user will be deactivated in HubSpot as well.
• Adding a user to HubSpot will not add the user to your identity provider.

​

Set up SCIM with a new app

• If you haven’t already authenticated your account using the HubSpot CLI, run hs init. Learn more about installing the HubSpot CLI.
• Run the following command to create a project with configured with a boilerplate SCIM configuration file and set up the required project directory structure:

hs project create --platform-version 2025.2 --name scim-app --dest scim-app --project-base app --distribution private --auth static --features scim

​

Manage your SCIM configuration in your project

└── src/
    └── app/
        └── app-hsmeta.json
        └── scim/
            └── scim-hsmeta.json

{
  "uid": "scim-app",
  "type": "app",
  "config": {
    "description": "A private app for integrating an IdP with SCIM.",
    "name": "scim app",
    "distribution": "private",
    "auth": {
      "type": "static",
      "requiredScopes": [
        "crm.objects.users.read",
        "crm.objects.users.write",
        "settings.users.read",
        "settings.users.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": [],
      "iframe": [],
      "img": []
    }
  }
}

{
  "uid": "scim",
  "type": "scim",
  "config": {
    "roleSyncEnabled": false
  }
}

hs project upload

​

Install and manage SCIM in your HubSpot account

• In your HubSpot account, navigate to Development.
• On the Projects page, click the name of your project.
• On the Overview tab of the project details page, under Project Components, click the top-level app name as defined in the name field in your app’s top-level schema file.
• Under App Features click the scim component, as defined by the uid field of your scim-hsmeta.json file.

​

Add a verified domain

• On the SCIM component details page, click Add domain.
• In the right panel, enter the domain, then click Next.
• In the DNS settings of your domain provider, you’ll need to set up a TXT record with the provided Host (name) and Value fields with the values provided. Once configured in your domain provider, click Next.
• The verification process usually completes within an hour, but you may need to wait up to 48 hours for the new DNS information to propagate. Once verified, you’ll see the domain appear with a success state on the SCIM component details page.

​

Install the app in your account

• Click the Distribution tab on the SCIM component details page.
• Under the Manage distribution section, click Install now next to your account.

• You’ll be prompted to confirm that you’re allowing an unverified app to connect to your account. Review your app permissions then click Connect app.

• Back on the Distribution tab in your account, a new access token will appear next to your account. Click Show to view the token and Copy to copy the token to the clipboard. You can use this token, along with the Tenant URL of https://api.hubspot.com/scim/v2 in your identity provider settings to connect your new SCIM app.