canonical: https://jentic.com/apis/hubspot.com/hubspot-user-provisioning # HubSpot User Provisioning The HubSpot User Provisioning API manages the user directory of a HubSpot account: who has a seat, what role they hold, and which team they belong to. It supports inviting and removing users, fetching the role and team rosters, and updating an individual user's role assignment. Identity providers and HRIS systems use it to keep HubSpot's seat allocation in sync as people join, change teams, or leave the company. ## For AI agents List HubSpot users, teams, and roles; provision new users; update an individual user's role; and offboard users from the portal. ## Scope Does not configure SSO, set permission scopes, or manage app-level OAuth installs - use for HubSpot user, role, and team directory operations only. ## Capabilities - List every user with a seat on the HubSpot account - Invite a new user to the HubSpot account with a specific role - Retrieve a single user record by user ID - Update a user's role assignment without recreating the user - Remove a user from the HubSpot account to revoke access - List the teams configured on the portal for assignment - List the roles available on the portal for assignment ## Use cases ### HRIS to HubSpot user sync Keep HubSpot's seat list aligned with the source-of-truth HR system by reading new joiners and leavers nightly and pushing them through this API. New hires receive an invite with the correct role, and offboarded users are removed the day they leave so revoked access is enforced without manual cleanup. Example prompt: For each new joiner, POST /settings/v3/users/ with email and roleId; for each leaver, DELETE /settings/v3/users/{userId} to remove the seat. ### Role rebalancing during a reorg When sales territories or pods are restructured, update many users' role assignments at once without having to recreate accounts. Reading the role list first and patching each user keeps team membership and audit history intact while shifting permissions to the new structure. Example prompt: Call GET /settings/v3/users/roles to find the new role IDs, then iterate over affected users with PUT /settings/v3/users/{userId} to set the new roleId. ### Audit of HubSpot seat usage Generate a periodic seat audit by listing every user and joining the result against the role and team rosters to surface seats that no longer match an active employee or that hold a role richer than required. Finance and security teams use the same join to confirm that paid seat counts match contract terms. Example prompt: Call GET /settings/v3/users/, GET /settings/v3/users/roles, and GET /settings/v3/users/teams, then merge the records and flag any user whose role exceeds their job function. ### Agent-driven onboarding through Jentic An onboarding agent triggered by an HRIS new-hire event uses Jentic to find the HubSpot user invite operation, loads the schema, and provisions the seat with the right role and team. Jentic's vault holds the HubSpot OAuth token so the same agent can run safely against multiple HubSpot portals in a multi-tenant setup. Example prompt: Through Jentic, search 'invite a HubSpot user', load the schema for POST /settings/v3/users/, and execute it with the new hire's email and the AE roleId. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /settings/v3/users/ | List all users on the portal | | POST | /settings/v3/users/ | Invite a new user to the portal | | GET | /settings/v3/users/{userId} | Retrieve a single user record | | PUT | /settings/v3/users/{userId} | Update a user's role assignment | | DELETE | /settings/v3/users/{userId} | Remove a user from the portal | | GET | /settings/v3/users/roles | List available roles | | GET | /settings/v3/users/teams | List configured teams | ## Key resources - **Users** — List, invite, retrieve, update, and remove HubSpot users - **Roles** — List the roles available for assignment to users - **Teams** — List the teams configured on the portal ## Why Jentic - **Setup:** Wiring HubSpot User Provisioning by hand means running its OAuth flow or minting a private-app token, targeting api.hubapi.com, and mapping users to role and team ids yourself. Through Jentic you install once, import HubSpot User Provisioning from the API Directory, store the credential once, and your agent calls it. - **Permission scoping:** This API puts the user id in the URL path (/settings/v3/users/{userId}), so a rule can pin your agent to one user: it can read and update that user and nothing else. You choose the operations it may call, so deleting a user is not included unless you add it. - **Credential handling:** Your HubSpot OAuth or private-app token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'invite a HubSpot user' or 'list HubSpot roles', and Jentic returns the matching User Provisioning operation with its input schema, including the userId and roleId fields, so the agent calls the right endpoint without browsing the HubSpot reference docs. ## Related APIs - **Okta** — Identity provider that drives the join-mover-leaver events feeding HubSpot user provisioning - **Auth0** — Identity platform alternative whose user lifecycle hooks can trigger HubSpot provisioning calls - **OneLogin** — Alternative identity provider for centralised user lifecycle management - **HubSpot CRM Users** — Sister HubSpot API for reading the user records that this provisioning API creates ## FAQ ### What authentication does the HubSpot User Provisioning API use? It accepts HubSpot OAuth 2.0 tokens and private-app tokens passed as a Bearer header. Through Jentic the credential is held in your encrypted Jentic One instance and injected at execution time, so the agent provisioning users never sees the raw token. ### Can I invite a user with a specific role and team? Yes. POST /settings/v3/users/ accepts the email plus the roleId returned from GET /settings/v3/users/roles and the primary team from GET /settings/v3/users/teams, so invites land with the correct permissions from day one. ### What are the rate limits for this API? HubSpot's standard public API limits apply: 100 requests per 10 seconds for OAuth apps and 110 per 10 seconds for private apps. For nightly HRIS sync of large workforces, throttle the inviter loop to stay under that window. ### How do I offboard a user through Jentic? Search Jentic for 'remove a HubSpot user', load the schema for DELETE /settings/v3/users/{userId}, and execute it with the userId. The seat is freed and the user can no longer sign in to the portal. ### Does this API replace SCIM provisioning? It can - the create, update, and delete operations cover the lifecycle most identity providers need to drive HubSpot. Use this API when your IdP does not have a native HubSpot SCIM connector, or when you need finer control than the SCIM mapping allows. ### Can I change a user's role without recreating the user? Yes. PUT /settings/v3/users/{userId} updates the roleId in place, preserving the user's history, owned records, and login. Recreate the user only when the email itself needs to change. ### Can I limit what my agent is allowed to do with the HubSpot User Provisioning API? Yes. Jentic One runs self-hosted, so your own rules decide which of the seven operations the agent may call: you can allow it to list users, invite a user, or update a role while excluding DELETE /settings/v3/users/{userId} so it can never remove a seat. Because the user id sits in the path (/settings/v3/users/{userId}), a rule can pin the agent to a single user, letting it read and update only that record. The HubSpot OAuth or private-app token stays with your instance and is injected at call time, so the agent never handles the raw credential.