SCIM provisioning reference
The protocol surface RoundUp exposes to an identity provider — for the person configuring a connector, or reviewing one.
At a glance
| Protocol | SCIM 2.0 — RFC 7643 (schema), RFC 7644 (protocol) |
| Role | Service provider (server). RoundUp never acts as a SCIM client. |
| Resources | User only. No Group resource. |
| Authentication | HTTP Bearer token, issued per center and per provider |
| Tenancy | One center per token. The token names the center it provisions. |
| Content type | Responses are application/scim+json; request bodies are parsed as JSON whatever their content type. |
An active user creates an invited staff account at the center — a membership plus the invitation email — and is a no-op for someone who is already a member. Deactivating or deleting a user removes their membership of the center and signs out any session they have open within about a minute. Name changes to an existing member are stored on the SCIM record but not copied to their RoundUp staff record.
Endpoints
Each identity provider has its own base path, and a token is only valid on the base path of the provider it was issued for. Copy the exact values from the provisioning section of the connect screen in the app — Show provisioning details for JumpCloud, SCIM connector base URL for Okta.
| Provider | SCIM base URL |
|---|---|
| JumpCloud | https://integrations.roundupece.com/integrations/jumpcloud/scim/v2 |
| Okta | https://integrations.roundupece.com/integrations/okta/scim/v2 |
Discovery endpoints are served on each base path and require the same credential as any other call: /ServiceProviderConfig, /ResourceTypes and /Schemas. Only the collection forms exist — /ResourceTypes/User and /Schemas/<urn> return 404. /Schemas describes userName, active, emails and name. The Okta path also serves a read-only /Entitlements collection.
Authentication
Every request carries Authorization: Bearer <token>. The token is an HMAC-signed assertion of a single center's identifier, signed with a key specific to the provider, so a JumpCloud token is refused on the Okta path and neither can reach another center's records.
A new token is signed each time the provisioning details are shown in the app. Earlier tokens keep working — they don't expire and can't be revoked one at a time — so treat each one like a password and don't paste it anywhere you wouldn't paste one.
There is no OAuth flow on the JumpCloud path. The Okta path additionally accepts a one-hour access token from its token endpoint using the client_credentials grant; its authorize endpoint always refuses. ServiceProviderConfig reports the scheme as oauthbearertoken, which is SCIM's name for bearer-token authentication.
Supported operations
| Method | Path | Behaviour |
|---|---|---|
GET | /Users | List. filter supports eq on userName, externalId, emails or emails.value, case-insensitively; any other filter returns every user rather than an error. startIndex and count are honoured. |
POST | /Users | Create. 409 uniqueness if the userName (case-insensitive) already exists for this provider at this center. |
GET | /Users/{id} | Read. |
PUT | /Users/{id} | Full replace. Omitted attributes are cleared, and a body without active sets it to true. |
PATCH | /Users/{id} | add and replace (with or without a path) and remove (with a path) on active, userName, displayName, name.givenName, name.familyName, emails (whole array) and externalId. Other paths, including name as a whole, are ignored without an error. Not currently routed on the JumpCloud path. |
DELETE | /Users/{id} | Deletes the SCIM record; later reads return 404. Returns 204. |
ServiceProviderConfig
| Capability | Supported |
|---|---|
| patch | Yes |
| filter | Yes — advertises maxResults 200, which isn't enforced |
| bulk | No |
| sort | No |
| etag | No |
| changePassword | No |
User attributes
Required. userName, or failing that an emails entry with a value. A create with neither — or with a body that isn't valid JSON — returns 400 invalidValue.
The address used to match a provisioned user to a RoundUp account is the first emails value, or the userName when there are no emails and it's an address. A non-email userName with no emails array creates a SCIM record that could never match a staff account.
| Attribute | Handling |
|---|---|
userName | Stored. Falls back to the first email value. |
emails | Stored. Synthesized from userName when that is an address. |
name | Stored as sent, including any sub-attributes. |
displayName | Stored and returned. |
active | Stored, defaults true. A string counts as true only when it's "true". |
externalId | Stored when sent. |
entitlements | Stored when sent. |
Everything else is discarded — not stored, and absent from the read-back. That includes phoneNumbers, addresses, title, userType, locale, timezone, photos, ims, nickName, profileUrl, preferredLanguage and password. A connector that writes one of these and reads it back will not find it.
No attribute can make anyone a director, assistant director or admin. On the Okta path, an entitlement names a teacher-level role — LEAD_TEACHER, TEACHER or ASSISTANT_TEACHER — and TEACHER is the default. title and userType are ignored so that editing a title field in a directory cannot grant access to children's records. See Roles and permissions.
Deactivation
Setting active to false, by PATCH or PUT, keeps the SCIM record with active: false. DELETE removes the record entirely. Both return success.
Both remove the person's membership of the center and sign out every session they have open within about a minute, including on a shared classroom tablet. Their identity and any memberships at other centers are left alone, and their history stays attributed — incident reports, check-ins and medication logs are licensing records the center must keep. Re-provisioning creates the membership again.
The center owner cannot be deprovisioned this way; that request is refused, so removing the wrong person in a directory cannot lock a center out of its own account.
Errors
Errors use the SCIM Error schema, with detail, status as a string, and scimType where one applies.
| Status | scimType | Meaning |
|---|---|---|
400 | invalidValue | A create with no userName and no email value, including a create whose body isn't valid JSON. |
401 | — | Missing, malformed or unverifiable bearer token. |
403 | — | Provisioning isn't available for this center. |
404 | — | No such user, or an unknown path. A PATCH on the JumpCloud path currently gets a plain 404 before reaching the SCIM service. |
405 | — | Method not allowed on /Users or /Users/{id}. |
409 | uniqueness | That userName already exists for this provider at this center. |
500 | — | Provisioning is not configured on our side, or an unexpected error. |
Uniqueness is scoped to the provider within a center: a user already created by a different directory does not make this one's create fail. It's only checked on POST — a PUT or PATCH that renames a user to a duplicate userName isn't refused.
Limits and omissions
- No attribute sync for existing members. Name changes after an account exists are stored on the SCIM record only.
- No Group resource.
GET /Groupsreturns an empty list. Assigning a directory group to the application still scopes who your directory sends. - No password syncing. A
passwordattribute is discarded. RoundUp passwords are set by the staff member through their own invitation. - No bulk, sort or ETag support.
metacarries no version. - Filtering supports only the
eqexpressions above, andcountisn't capped — omitting it returns every user.
This page is the protocol reference. For step-by-step configuration see Connect JumpCloud or Connect Okta.
More: All director guides