Hoxhunt SCIM Provisioning: Transitioning from Bearer Token to OAuth Authentication

What this article covers: Hoxhunt now supports two ways to authenticate SCIM provisioning requests: a bearer token and OAuth 2.0 client credentials. This guide explains both, explains why a third setting (Bearer + OAuth) exists purely to make migration safe, and walks through moving an integration from bearer to OAuth without pausing provisioning.

Most customers do not need to do anything right now. If you provision through one of the Hoxhunt gallery apps, bearer token is still the correct setting. Check Which method applies to you first.

If you provision through Microsoft Entra ID, a change is coming. We are working on an updated Hoxhunt application for the Entra gallery, and once it is released it will require OAuth. There is nothing for you to do until then, and we will let you know. See Coming change for Microsoft Entra ID.

The two authentication methods

Both methods protect the same SCIM 2.0 endpoint. Only the credential differs.

Why OAuth is the better default. The credential your IdP stores gets exchanged for a token that expires in an hour, so a leaked access token stops working on its own. A bearer token never expires. If it leaks, it stays valid until somebody notices and rotates it. OAuth also lets you run two credentials side by side, which is what makes both migration and routine rotation zero-downtime.

Which method applies to you

The method you use is decided by how you connect to Hoxhunt, not by preference. Find your row before following any steps.

If your row says Bearer token, the rest of this guide does not apply to you today. Nothing about your setup is changing and no action is needed. The migration steps below are for moving a custom bearer integration to OAuth.

If you provision through a gallery app, don't switch your organization to OAuth just because it is available. The gallery app has to support it first, otherwise provisioning will start failing.

Coming change for Microsoft Entra ID

We are working on an updated Hoxhunt application for the Microsoft Entra ID gallery. When that app is released it will require OAuth, because Microsoft's gallery requirements no longer allow provisioning secrets that never expire. Bearer token will not be an option on it.

What this means for you if you provision through Entra ID:

• Nothing to do today. The app currently in the gallery keeps working with your bearer token.

• When the new app is released, you will need to move to OAuth. We will let you know, and this guide will carry the steps for it.

• If you want to get ahead of it, the useful preparation is knowing who in your organization can edit the Hoxhunt provisioning app in Entra, and having a maintenance window in mind. Don't create OAuth credentials or change your authentication method yet.

We don't have a release date to share, so please don't plan the migration around a specific week until we confirm one.

Bearer + OAuth ("dual"): the migration bridge

The third option in the authentication method selector is Bearer + OAuth. Its only job is to let you change credentials in your IdP at a different time than you change settings in Hoxhunt.

While it is selected, Hoxhunt accepts either credential type. That removes the ordering problem. Without it you would have to flip Hoxhunt to OAuth and reconfigure your IdP at the same instant, and provisioning would fail in the gap between the two.

Bearer + OAuth is a temporary state, not a destination. As long as it is selected, the old bearer token still works, so it is still a live credential you have to protect. Finish the migration by selecting OAuth token and letting the bearer token go.

  Bearer token  >>  Bearer + OAuth  >>  OAuth token
   (today)           (during the         (target)
                      migration)

Before you start

• You need Hoxhunt admin access to Settings → Organization → Automated user provisioning.

• You need permission to edit the Hoxhunt provisioning app in your identity provider.

• Have a maintenance window or a quiet period in mind. Nothing here requires downtime, but you want to be able to watch one provisioning cycle complete.

• Your SCIM endpoint URL does not change. Copy it from the admin page; on production it is https://app.hoxhunt.com/services/scim.

Migration steps

Follow these only if the table above put you on OAuth, or if Hoxhunt Support has told you to migrate. They work for any identity provider or script that can perform an OAuth client-credentials exchange.

1. Switch Hoxhunt to Bearer + OAuth

In Settings → Organization → Automated user provisioning, select Bearer + OAuth and confirm. Your existing bearer token keeps working exactly as before, so nothing in your IdP breaks at this point.

2. Create OAuth credentials in Hoxhunt

Click Create OAuth credentials, give the client a name you will recognise later (for example HR provisioning script or OneLogin production), and confirm.

Hoxhunt shows you:

• Client ID

• Client secret

• Token URL

• Expires at, which is 3 years from creation

3. Configure your identity provider to use OAuth

Update the Hoxhunt provisioning app in your IdP to use the client ID and secret. The details depend on the IdP:

• A gallery app (Microsoft Entra ID, Okta): the app decides which credential it can send, and the apps in the galleries today send a bearer token. Don't change anything here.

• An IdP with native OAuth client-credentials support: enter the Token URL, Client ID and Client secret in its provisioning credentials section. No scope is required.

• An IdP or script that only accepts a static bearer token: it can't do the token exchange itself. Keep using the bearer token for that integration, or fetch access tokens yourself using the token endpoint reference and refresh them at least every 60 minutes.

4. Verify provisioning works on the new credentials

Trigger a provisioning cycle from your IdP (on-demand provision of a single user is usually enough) and confirm:

• The IdP reports success, not an authentication error.

• Last provisioned at on the Hoxhunt SCIM settings page updates to the current time.

• A test user change, such as a name or department update, lands in Hoxhunt.

Don't move on until this passes. While you are in Bearer + OAuth, a misconfiguration can be masked by the IdP quietly falling back to the bearer token it still has stored. Check that the credential you intended is the one in the IdP config.

5. Switch Hoxhunt to OAuth token

Select OAuth token and confirm. From this point Hoxhunt expects OAuth access tokens for SCIM provisioning, and the bearer token is no longer part of your setup.

6. Clean up

• Delete the old bearer token value from any password manager, runbook, ticket, or script where it was stored. It is a long-lived secret and should not outlive the migration.

• Revoke any OAuth clients you created by mistake (Revoke next to the client).

• Note the client secret's Expires at date somewhere you will actually see it. See Keeping credentials healthy.

Rolling back

If provisioning breaks after step 5 and you need to restore service immediately:

1. Select Bearer + OAuth again. Your bearer token becomes accepted again.

2. Point your IdP back at the bearer token.

3. Confirm Last provisioned at updates, then investigate the OAuth

   configuration without time pressure.

Rollback only works if you still have the bearer token value. If you already completed step 6 and destroyed it, create a new one from the Bearer section instead. Creating a bearer token replaces any previous one, which is harmless here since you aren't using it.

Keeping credentials healthy

Client secrets expire after 3 years. Hoxhunt warns you on the SCIM settings page when a secret is within three months of expiry, and shows an error once it has expired. An expired secret can no longer be exchanged for an access token, so provisioning stops.

Rotate without downtime. This is the payoff for being on OAuth:

1. Create a second OAuth client (up to 3 can exist at once). The existing one

   keeps working.

2. Update your IdP to the new client ID and secret.

3. Confirm one successful provisioning cycle.

4. Revoke the old client.

Revoking is immediate and permanent. The client ID and secret stop working right away, and any access token already issued to that client stops working too. Revoke only after the new credential is confirmed working.

Troubleshooting

Token endpoint reference

For identity providers that need OAuth configured manually, and for custom provisioning scripts.

Token endpoint

POST https://app.hoxhunt.com/services/scim/oauth2/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

• Grant type: client_credentials only.

• Client authentication: HTTP Basic. No scope parameter is needed.

• The endpoint is rate limited, though a normal provisioning cadence stays well under the limit. Don't request a fresh token per SCIM request, cache it instead.

Success response

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Error response (HTTP 400/401)

{
  "error": "invalid_client",
  "error_description": "..."
}

Using the access token

GET https://app.hoxhunt.com/services/scim/Users
Authorization: Bearer <access_token>

Re-request a token before the previous one expires (expires_in is 3600 seconds).