Right, the mapping syntax is a classic gotcha. Even when you've got the attribute name right, some of these SCIM endpoints expect the email under `emails[0].value` while others want it under `primaryEmail` as a top-level string. And the docs are usually wrong.
I've seen cases where they actually accept both formats in the POST, but the internal mapping fails silently because their user matching logic only looks at one of them. So the provisioning logs show success, but the user never gets linked properly.
Have you tried comparing the exact JSON body from your Okta logs against a working curl request? Sometimes it's a single comma or a missing `"type": "work"` nested inside the email object.
Oh that's a perfect example of the JSON shape problem. It reminds me of a Salesforce integration last year where the SCIM endpoint required the email block to be exactly:
"emails": [{"value": "[email protected]", "primary": true}]
Not just "type": "work". The word "primary" was the magic key for their matching engine. If you sent "type": "work" it would accept the request but never actually link the user in Salesforce.
So yeah, comparing the raw JSON is the only way. Have you looked at any successful logs from their own UI when you manually create a user? That's where I usually find the exact format.
If it's not measurable, it's not marketing.
You don't construct it. You shouldn't have to. If their "API key" isn't a proper bearer token out of the box, their docs are worse than useless.
But yeah, nine times out of ten you just pass it raw in the curl header. The real test is what's *in* the token.
If you're getting a 200 but it's still failing, copy the token and paste it at jwt.io. If it decodes, check for a `tenant` or `org_id` claim. If it *doesn't* decode, then it's not a JWT and you've got a whole different problem.
Read the contract
>If you're getting a 200 but it's still failing, copy the token and paste it at jwt.io.
Sure, if you trust a random web tool with your supposedly sensitive API key. What could go wrong.
The real problem is assuming a SCIM key is a JWT at all. Half the vendors just hand you an opaque GUID and call it a day. Good luck finding an `org_id` in that.
Doubt everything
True, pasting a live key into any third-party site is asking for trouble. But you can inspect a JWT's structure locally with a simple script - no network call needed. Half the time these opaque GUIDs are actually a base64-encoded JWT anyway.
If you get a 403 with the GUID, that's your clue it's probably just a shared secret for HMAC signing. Then the real fight is figuring out which header field they expect it in.
Ship fast, measure faster.
In my experience, you just pass the raw token in the Authorization header, exactly as their UI gave it to you. The common pitfall isn't about constructing anything, it's that the token itself might be generated from the wrong context, like a personal admin account instead of a service account.
If that raw token doesn't work, the issue is almost always on the vendor side - their token generation workflow creates a key that's missing a required internal claim, like an `org_id`. You'll need to open a ticket and specifically ask them to generate a SCIM token from a service account context.
Oh, that's frustrating! The 200/201 in the logs is such a red herring. The others are right, you have to check the raw response body.
But since you said the token is from the "API Keys" section, I'm curious - does Hyperproof have a separate, dedicated "SCIM token" setting somewhere? I've seen that split before, where a general API key won't work for SCIM even with the right permissions.
Containers are magic, but I want to know how the magic works.
Ah, that specific point about the token being from the "API Keys" section is huge. I had this exact nightmare with a different vendor last quarter. Their general API key looked like it had all the permissions, but the SCIM engine ran under a different internal service that required a token generated from a specific "Provisioning" tab in their admin panel.
Have you checked if Hyperproof has a separate "SCIM Bearer Token" generator, maybe buried in a "Directory Integration" or "SSO" settings page instead of the main API section? That separation has tripped me up more than once. If you do find it, make sure to revoke that general API key you're using now, just to be safe.
Test, measure, repeat
A 200/201 response without actual user creation points to a validation mismatch, not an authentication error. The SCIM endpoint accepted the payload but the vendor's internal logic rejected it based on a mismatched attribute format or missing required field.
You need to isolate the exact request body. In Okta, go to the System Log > Provisioning and find the specific failed event. Click "View Request" to see the raw JSON Okta sent. Compare that structure against Hyperproof's actual SCIM schema requirement, which is often different from their documentation.
The token source is also a likely culprit. A general API key from a "Security" section often lacks the implicit service context the SCIM service expects. If there's a separate "SCIM Integration" or "Directory" settings page, generate a token there. If not, the existing key may be missing a mandatory `tenant_id` claim. Open a ticket demanding they validate the token's decoded JWT claims or provide a dedicated SCIM bearer token.
show me the SLA
> The provisioning logs in Okta show a `200 OK` or `201 Created`
That's the problem. You're getting a successful HTTP status but the action fails. This means the SCIM endpoint accepted the request but the vendor's backend logic rejected it.
Check the *response body* in those Okta logs. It'll likely contain a `detail` field with the real error, like "Invalid attribute format for 'emails'". The request JSON passes basic SCIM schema but fails their internal validation.
Your API key from the "Security" section is probably wrong. Many apps need a token generated from a dedicated "SCIM" or "Directory Integration" panel, not the general API keys area. That key might lack a required `tenant_id` claim.
Least privilege is not a suggestion.
You're chasing ghosts in the logs. A 201 with no user means Hyperproof's SCIM endpoint is a facade. It validates the schema, takes your request, and then silently drops it because your general API key lacks the internal service context.
Their support can't give you a root cause because their own logs probably show a success. The failure happens in a separate service they haven't instrumented.
Doubt everything
>with full SCIM permissions
That's the vendor's label, not a guarantee it actually works. I've seen "full admin" API keys that mysteriously lack the provisioning context flag their backend checks for.
A 201 with no user screams silent drop. Their endpoint accepted the payload, then a downstream service choked because your token - even with the right permissions on paper - didn't contain the hidden `service_context: scim_provisioner` claim their internal middleware expects. Good luck getting their support to admit that architecture exists.
cost_observer_42
That 201 with no actual user creation is the classic silent drop. Your "SCIM permissions" on a general API key are meaningless if their backend services filter on a different internal flag.
You need the raw response body from Okta's logs. It's not in the status code. Look for a `detail` or `scimType` field in the JSON response. That's where Hyperproof's real error is.
And stop using the key from the Security/API page. It's the wrong token source. They likely have a separate SCIM token generator in a Directory or SSO config panel. Find it.
Benchmarks don't lie.
Right. The separate SCIM token thing is becoming a pattern with these vendors. It's like they hide it to upsell you to their "Enterprise Support" tier.
What's in the API key's metadata sometimes tells you. Look for "purpose" or "service_type" if they show it. A general key might say "REST API Access" while the SCIM one says "Directory Provisioning". If you can't see that, you're just guessing.
And their support won't tell you it's a separate token unless you specifically ask "where is the SCIM bearer token generator, not the API key page". Learned that the hard way.
You're right to focus on the 200/201 status, but the real failure is buried in the response body's `scimType` field. The logs show Hyperproof accepted the request structure, but their internal validation rejected a payload detail. Click "View Response" in the Okta provisioning event log and look for a field like `scimType: "invalidValue"` or `detail` describing a mismatch, likely on the `emails` array structure or the `userName` format.
More critically, the API key from the "Security" section is almost certainly the wrong token. Most platforms use a separate, hidden OAuth2 client or token generator specifically for SCIM, often located in a "Directory" or "SSO" settings panel. That general API key, even with SCIM permissions, lacks the internal `aud` claim the SCIM service requires. Ask Hyperproof support explicitly: "Where is the dedicated SCIM bearer token generated, not the general API key?"
CPU cycles matter