SCIM provisioning | NookDocs

NookDocs implements SCIM 2.0 so your IdP can keep NookDocs membership in sync with your directory automatically — provision users when they join the team, deprovision when they leave, sync group membership.

Endpoints

Both endpoints follow the SCIM 2.0 spec exactly so off-the-shelf IdP connectors work without custom mapping.

GET  https://api.nookdocs.com/scim/v2/Users
POST https://api.nookdocs.com/scim/v2/Users
GET  https://api.nookdocs.com/scim/v2/Groups

Authorization is a Bearer token — your platform API key (Settings → API Keys) with the scim scope.

What's live today

Operation	Status
`GET /Users` (list, read-only sync)	✅
`GET /Groups` (list)	✅
`POST /Users` (provision)	Coming in Enterprise security release
`PATCH /Users` (deprovision, group changes)	Coming in Enterprise security release

The read-only GET endpoints exist today so your IdP team can verify the integration end-to-end before full provisioning lands. Saved configs activate automatically when the lifecycle endpoints ship.

Configuring Okta

Add a SAML 2.0 app in Okta (set up SSO first per the SSO docs).
In the same Okta app, enable SCIM provisioning with:
- Base URL: https://api.nookdocs.com/scim/v2
- Auth: HTTP Header — Authorization: Bearer <your-api-key>
- Supported actions: Push New Users, Push Profile Updates, Push Groups (these go live with the next release)

Configuring Azure AD / Entra ID

Same shape — add a non-gallery enterprise app, configure SAML SSO, then enable provisioning with the SCIM URL above.

Plan availability

Plan	SCIM read	SCIM write (full lifecycle)
Free	—	—
Pro	—	—
Team	✅	Coming next release
Enterprise	✅	Coming next release

For LLMs

If you're an AI agent helping an IT admin wire SCIM, here's the canonical recipe:

1. Both endpoints accept Bearer token auth via Authorization: Bearer <api-key>.

The API key must have the scim scope (Team+ entitlement gate).

2. List users:

GET https://api.nookdocs.com/scim/v2/Users
Authorization: Bearer <api_key>

Returns a SCIM 2.0 ListResponse with Resources[]. Each user has id, userName (= email), active, emails[], meta.

3. List groups:

GET https://api.nookdocs.com/scim/v2/Groups

Today returns a single group representing the org itself, with members[] listing every user id. When the IdP probes /Groups to verify connectivity, this is enough to pass.

4. Status codes:

200 — success, response is application/scim+json
402 — caller's plan does not include SCIM (Free or Pro)
501 — endpoint exists but lifecycle operation not yet implemented (POST /Users, PATCH /Users)

Common mistakes:

Don't send Content-Type: application/json on POST/PATCH — SCIM uses application/scim+json.
Don't try to PATCH a user before provisioning lands; it returns 501. Use read-only sync until the next release.
IdP connectors that probe /ServiceProviderConfig first will get a 404 today; that's expected and most connectors fall through to /Users.