Provisioning with SCIM
SCIM 2.0 lets an Enterprise organisation's identity provider add, update and remove its members in Plotwork, and give them roles by group. This page covers what Plotwork reads and how to connect any SCIM 2.0 provider. For Microsoft Entra ID and Okta, follow their own pages, which name every screen.
TL;DR
| Question | Answer |
|---|---|
| Which plan? | Enterprise. On another plan every SCIM call is refused with 403. |
| What do I need first? | An email domain verified on the Single sign-on tab. Your provider can only create people whose address is on it. Single sign-on itself does not have to be on. |
| Where are the values? | The organisation's Single sign-on tab, the Provisioning with SCIM section: the SCIM base URL, and a token from Make token. |
| SCIM base URL | https://api.plotwork.dev/scim/v2/<organisation id>. Paste it where your provider asks for the tenant URL, the SCIM connector base URL or the SCIM endpoint. |
| Token | Starts with pwscim_, shown once. Paste it where your provider asks for the secret token, the bearer token or the API token. It is sent as Authorization: Bearer <token>. |
| Which provider? | Microsoft Entra ID, Okta, or any provider that speaks SCIM 2.0 with a bearer token, such as OneLogin, JumpCloud or Ping Identity, with the steps below. |
| What decides roles? | Groups your provider pushes, each mapped to Admin, Member or Reader under Groups and roles. Until one group gives a role, SCIM never changes anyone's role. |
1. Make the token
- Open the organisation in the portal, then the Single sign-on tab, and verify a domain under Email domains if you have not.
- Open Provisioning with SCIM and press Make token.
- Copy the token at once: it is not shown again. Plotwork keeps only a hash of it and its first characters, so you can tell tokens apart.
- Copy the SCIM base URL beside it.
One token is live at a time. Replace token makes a new one and stops the old one at the same moment, so paste the new one into your provider straight after. Revoke token stops provisioning until you make another. The owner or an admin makes the token; an API key cannot.
2. Connect your provider
At your provider, add a SCIM 2.0 application, or turn on provisioning for the Plotwork app you sign in with, and fill in:
| Your provider asks for | Paste |
|---|---|
| Tenant URL, SCIM connector base URL, SCIM base URL or SCIM endpoint | The SCIM base URL, with nothing added at the end. Your provider adds /Users and /Groups itself. |
| Secret token, bearer token, API token or Authorization header | The token. Where the provider asks for the whole header, write Bearer and then the token. |
| Authentication method or mode | Bearer token, or HTTP header. Basic authentication and OAuth are not offered. |
| Unique identifier, or the matching attribute for users | userName |
| Matching attribute for groups | displayName |
Turn on creating users, updating user attributes, deactivating users, and pushing groups, if your provider lists them separately.
3. Map the attributes
Plotwork keeps a few attributes and accepts the rest without keeping them, so a provider's default mapping works as it is.
| SCIM attribute | What Plotwork does with it |
|---|---|
userName | Required. The person's email address, on a domain you verified. It cannot change later. |
emails | Read only when userName is not an address: the primary address, or the work one, or the first. |
active | false deactivates the person, true brings them back. "True" and "False" as text are read too. |
name.givenName, name.familyName | Kept as the person's name, up to 100 characters each. |
externalId | Kept, so your provider can find the person by its own id. Up to 255 characters. |
| Any other attribute | Accepted and ignored. |
Group displayName | The group's name under Groups and roles. Up to 200 characters. |
Group members | Who is in the group: each a user your provider made here. |
Map your provider's email or user principal name to userName, whichever is the address people use.
4. Assign people and push groups
Your provider sends only the people and groups you assign to the app. Assign them, then push the groups whose roles you want Plotwork to follow.
| What your provider does | What happens in Plotwork |
|---|---|
| Creates a person | The address must be on a verified domain. The account is found or made, and they join as a member, within your member limit. |
| Updates a person | Their name follows the provider. Their address cannot change: deprovision them and create the new one. |
| Deactivates a person | They leave the organisation at once, and every session they opened through your provider ends. Their API keys and agents stop at their next call. |
| Deletes a person | The same, and the provider's record of them goes. Their Plotwork account stays, with their own diagrams and other organisations. |
| Pushes a group | It appears under Groups and roles, with its members. An organisation holds up to 200 groups. |
The owner is linked like anyone else, and never changed or removed.
5. Map groups to roles
Under Groups and roles, choose the role each group gives: Admin, Member, Reader or No role.
| While | A provisioned person's role |
|---|---|
| No group gives a role | Never changed by SCIM. Set roles on the Members tab as usual. |
| Any group gives a role | The highest role their groups give, or Member when none of theirs gives one. It changes as your provider moves them between groups. |
Every change of role is recorded in the audit log as a role that followed SCIM groups. A person you added by invitation, and not through SCIM, is not changed. A role that cannot connect agents, such as Reader, disconnects the agents that person connected to the organisation.
6. Test it
- Assign one person whose address is on your verified domain, and run your provider's test or on-demand provisioning for them.
- In Plotwork, the section says how many people your provider provisioned, and the person appears on the Members tab.
- Unassign them, or deactivate them at your provider, and check that they leave the organisation.
To check the connection from a terminal, ask for one user:
curl -H "Authorization: Bearer $PLOTWORK_SCIM_TOKEN" "https://api.plotwork.dev/scim/v2/<organisation id>/Users?count=1"A working token answers 200 with a SCIM list. /ServiceProviderConfig, /ResourceTypes and /Schemas say what Plotwork supports.
What Plotwork supports
| Feature | Supported |
|---|---|
| Users | POST, GET, PUT, PATCH and DELETE /Users |
| Groups | POST, GET, PUT, PATCH and DELETE /Groups, and excludedAttributes=members |
| Filters | userName eq, externalId eq and id eq on users; displayName eq, externalId eq and id eq on groups. Nothing else. |
| Paging | startIndex and count, at most 100 a page |
| PATCH | add, replace and remove, at most 100 operations, with a path or an object of attributes |
| Not supported | Bulk operations, sorting, ETags and password changes |
| Rate limit | 600 calls a minute; past it, 429 |
| Request size | 256 KB a request |
Troubleshooting
Every refusal is a SCIM error with a status and a sentence. Your provider's provisioning log shows both.
| Status and message | What to check |
|---|---|
| 401 "A valid SCIM token for this organisation is required." | The token was replaced or revoked, was pasted with a space or without Bearer , or belongs to another organisation. Make a new one and paste it again. |
| 403 "SCIM provisioning is part of the Enterprise plan" | The organisation is not on Enterprise, or its contract ended. |
| 404 "No such SCIM service." | The base URL is wrong: copy it again from the tab, with nothing added. |
| 400 "The address is not on a domain the organisation verified for single sign-on." | The person's userName is on another domain, such as a onmicrosoft.com address. Map the address people use to userName, or verify the domain. |
| 400 "userName, or a primary email, must be an email address." | userName is not an address and no email was sent. Map an address to userName. |
| 409 "A user with this userName already exists." | Your provider lost track of a person it made. Match users on userName so it finds them. |
| 403 "The organisation has no free seats." | The member limit is reached. Raise it, or deprovision someone first. |
| 400 "userName cannot change." | The person's address changed at your provider. Deprovision them and provision the new address. |
| 400 "Only filters of the form attribute eq "value" are supported." or "Filtering on ... is not supported." | Your provider matches on an attribute Plotwork does not filter. Match users on userName and groups on displayName. |
| 400 "An organisation can have up to 200 groups." | Push only the groups that give a role. |
| 429 "Too many requests." | Your provider sent more than 600 calls a minute. It retries on its own. |
See also
| Page | Why |
|---|---|
| SCIM with Microsoft Entra ID | Every screen in the Microsoft Entra admin center |
| SCIM with Okta | Every screen in the Okta Admin Console |
| Single sign-on | Verifying a domain, and signing people in through the same provider |
| Organisations | Roles, members and the member limit |
| Audit log | Where every SCIM change is recorded |