Skip to main content

Set up SCIM Provisioning in Hook

Guide on setting up SCIM provisioning for users in Hook

Overview

SCIM (System for Cross-domain Identity Management) is a standard protocol that lets your identity provider (such as Okta or Microsoft Entra ID) automatically sync user access changes to Hook. Instead of manually updating roles or management hierarchy in Hook whenever someone joins, moves teams, or changes role, SCIM keeps Hook in sync with your identity provider.

Hook supports SCIM for managing user access, specifically user roles and management hierarchy. SCIM does not create or delete users in Hook. User creation and deletion is handled separately using Hook's user settings or your employee data system.

👤 Managers and Technical Admins have access to these settings in Hook

Prerequisites

  • You must have a Technical Admin or Manager role in Hook.

  • Your SSO integration (Okta or Microsoft Entra ID) should already be configured before setting up SCIM. If you haven't done this yet, see the setup guides for Okta SSO and Microsoft SSO first. Note: This is set up during implementation, so speak to your technical implementation consultant or reach out to [email protected]

  • You will need access to your identity provider's admin console to configure the SCIM connector.

  • You will need to generate a secure API key before starting. Hook recommends using at least 32 characters. You can generate one using a tool such as passgen.co. Optionally, you can include a UNIX timestamp as an expiry date for the key - use a converter such as unixtimestamp.com to generate one.

Setting up SCIM provisioning

Step 1: Configure SCIM in Hook

  1. In Hook, go to Configuration → Integrations → SCIM (or use this link).

  2. Enter your generated API key in the API key field.

  3. If you are using an expiry date, enter the UNIX timestamp for that date.

  4. Save the integration.

Note: Once you have added the SCIM integration, you will no longer be able to modify user roles directly on the Members page in Hook. Role management will be handled through your identity provider from this point on.

Step 2: Configure your identity provider

  1. In your identity provider (Okta, Microsoft Entra ID, or equivalent), open the SCIM connector settings for your Hook application.

  2. Enter the following SCIM connector details:

    • SCIM Version: 2

    • SCIM connector Base URL: https://scim.hook.co/v2/[customer_name]/ -replace [customer_name] with your Hook customer ID. This is usually the lower case name of your organisation (E.g. for Hook, this would be hook). Contact [email protected] if you're not sure where to find this.

    • Unique identifier for users: id

    • Authentication mode: HTTP Header

  3. In the authentication/token field, enter the same API key you generated in Step 1 as a Bearer Token.

  4. Save your identity provider configuration.

Step 3: Configure attribute mapping

You will need to map your identity provider's user attributes to Hook's attributes. The supported provisioning actions are Push profile updates and Push groups.
​

The Hook user schema includes the following attributes:

  • id: Unique identifier for the user. Type: number. Read-only. Always returned.

  • email: The user's email address. Type: string. Read-only. Always returned.

  • userName: Unique identifier for the user. Type: string. Read-only. Always returned.

  • managerEmail: The email address of the user's manager (or null if none). Type: string. Read/write. Always returned.

  • role: The role assigned to the user. Type: string. Read/write. Valid values: technical_admin, admin, manager, member, viewer.

The full attribute schema is also available from the schemas endpoint at your SCIM base URL. See the attached file at the end of this article.

Verification

To confirm your SCIM setup is working correctly:

  • In your identity provider, trigger a sync for a test user who is already in Hook.

  • Check that the user's role and manager information in Hook reflects what was pushed from your identity provider.

  • Confirm that users assigned to the Hook application in your identity provider appear with the correct roles in Hook after the sync completes.

Troubleshooting

Users assigned in the identity provider are not appearing or updating in Hook

This is commonly caused by the SCIM endpoint URL or API token being entered incorrectly in your identity provider.

  • Double-check that the Base URL includes your correct customer name and ends with a trailing slash: https://scim.hook.co/v2/[customer_name]/

  • Confirm the API key in your identity provider exactly matches the one entered in Hook.

  • Make sure the authentication is set to HTTP Header / Bearer Token - not basic auth or another method.

SCIM endpoint URL is wrong

The full users endpoint URL follows this format: https://scim.hook.co/v2/[customerId]/Users. Make sure your identity provider is pointing to this URL and not a generic or incorrectly formatted path.

Role changes are not syncing

Check your attribute mapping in the identity provider. The role attribute must be mapped and set to one of the valid Hook role values: technical_admin, admin, manager, member, or viewer. Any value outside this list will not be accepted.

Users cannot be created or deleted via SCIM

This is expected behaviour. Hook's SCIM integration only supports pushing profile updates and groups. It does not support user creation or deletion. Manage user creation and deletion through Hook's user admin settings or your employee data system.

You can no longer edit user roles in the Hook Members page

Once SCIM is enabled, the Members page no longer allows direct role edits. Role management must be done through your identity provider. This is intentional - it prevents your identity provider and Hook from falling out of sync.

Error message when changing a user's role

If you see an error on the user admin page, Hook will display the specific error message rather than a generic one, so you can see exactly what went wrong and how to fix it. Email [email protected] if you're unable to resolve this issue.

❓Frequently asked questions

Can I use SCIM to create or delete users in Hook?

No. Hook's SCIM integration only manages user access — roles and management hierarchy. Creating and deleting users must be done through Hook's user admin settings or wherever your employee data is stored.

What happens to Member settings once SCIM is enabled?

Once you add the SCIM integration, you can no longer modify user roles directly on the Members page. Changes must come through your identity provider.

What do I use as the authentication token in my identity provider?

Use the same API key you generated and entered in Hook as a Bearer Token in the HTTP Header authentication field in your identity provider.

Can I set an expiry date on the API key?

Yes. When generating your API key, you can optionally include a UNIX timestamp as an expiry date. Use a tool such as unixtimestamp.com to generate the timestamp.

Which SCIM provisioning actions does Hook support?

Hook supports Push profile updates and Push groups.

I'm getting SSO login issues alongside my SCIM setup - where should I look?

SCIM issues and SSO login issues can sometimes appear together. Common causes include the SCIM endpoint URL or token being entered incorrectly, or users being assigned to the app in the identity provider but not yet synced. See this article for more information.

What are the attributes available?

You can find these attributes in the attached JSON schema below.

Attachment icon
SCIM Schema Hook.json
Did this answer your question?