SCIM and people directories
This page is for the owners and admins who bring their company's people into an organization. You will connect an identity provider over SCIM, so it adds, changes and removes people by itself, or pull a people directory, so writers can name the right person in an instruction.
The two do different jobs:
| SCIM provisioning | A people directory | |
|---|---|---|
| Who acts | Your identity provider pushes changes to instruction.md. | instruction.md pulls a list when an admin asks. |
| What it changes | Who is in the organization: people it adds can join, people it deactivates lose their membership. | Nothing about membership. Its people can only be named in instructions. |
| Where its people show | This organization, the built-in directory. | A directory of its own, such as Okta. |
Each has its own plan badge in its section below. Both are on Integrations ▸ Directories in the editor. The organization's own members are in This organization on every plan.
Before you start
- Who can do this: only an owner makes or rotates a SCIM token, because a token can add and remove every member. An owner or an admin revokes tokens, and adds, pulls, hides and removes directories. Every member can search the people and see the directories.
- What you need: an admin account in your identity provider or directory, and a token or credential it gives you for reading users.
- MCP tools: the tools on this page need a token with the
org:adminscope (org:admin). There is no CLI command for them.
Provision people with SCIM
Plans On Team and Enterprise
instruction.md is a SCIM 2.0 service provider (RFC 7643, RFC 7644). Each organization has the same base URL. The token says which organization a request is for.
Base URL: https://instruction.md/api/scim/v2
Authorization: Bearer imdscim_<the token> Make a token
Open Integrations ▸ Directories
Under This organization, the Automatic updates (SCIM) row says whether your identity provider is connected, and when it last pushed a change.
Choose Make a token
An owner sees Make a token (or Make another token when one works already). Admins see Owners.
Copy the token and the SCIM address
Your SCIM token is shown this once: paste it into your identity provider now, with the SCIM address. Then choose I've kept it.
The token starts with imdscim_. instruction.md keeps only its SHA-256, so nobody can show it again: make a new one if it is lost. Each token row says when it was made, by whom, and when it was last used.
With the MCP server, orgs_scim_tokens_create makes one. Its answer has the token once, in secret:
{ "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C", "label": "Okta" } {
"token": {
"id": "sct_01JXA4R7C2M9Q5T8V1W3Y6Z0B2",
"label": "Okta",
"state": "active",
"createdAt": "2026-11-22T09:20:11.204Z",
"createdBy": { "id": "usr_01JX7Q3B5D7F9H1K3M5P7R9T1V", "name": "Dana Kim" }
},
"baseUrl": "https://instruction.md/api/scim/v2",
"secret": "imdscim_<the token>"
} | Tool | What it does | Arguments |
|---|---|---|
orgs_scim_tokens_list | List SCIM tokens | orgId |
orgs_scim_tokens_create | Make or rotate a SCIM token | orgId, label (optional), replaces (optional), keepOldHours (optional), idempotencyKey (optional) |
orgs_scim_tokens_revoke | Revoke a SCIM token | orgId, tokenId |
Rotate or revoke a token
An organization has at most 5 working tokens. Revoke one before you make another.
- Rotate in the editor makes a new token and revokes the old one at once. Paste the new token into your identity provider straight away.
- To keep the old token working while you change it, call
orgs_scim_tokens_createwithreplacesandkeepOldHours(0 to 24). The old token stops at the end of that time, and the row says stops soon. It doesn't count towards the limit meanwhile. - Revoke (
orgs_scim_tokens_revoke) stops a token at once. The identity provider's next request with it is refused. People already provisioned stay.
{
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C",
"label": "Okta",
"replaces": "sct_01JXA4R7C2M9Q5T8V1W3Y6Z0B2",
"keepOldHours": 24,
"idempotencyKey": "rotate-okta-2026-11"
} With an idempotencyKey, the same call sent again answers the same token, so a retry after a lost answer doesn't make a second one.
What provisioning does
| Your identity provider | What happens here |
|---|---|
| Creates a user | The person is listed in This organization at once, as provisioned, and can be named in instructions. They aren't a member yet and take no seat. |
| The person signs in | instruction.md matches the email their sign-in verified to the user's email (the primary one, else the work one, else the first; or the userName if it is an address). They get an invitation to join as a member, "Your organization's identity provider added you", valid for 14 days. Accepting it makes them a member. |
| Updates a user | Name, email, job title, team, manager, picture and location change everywhere the person is named. |
Sets active to false, or deletes the user |
If they are a member, they lose their membership and their roles in the organization's workspaces. They stay listed, marked as no longer here, so instructions that name them still say who they were. |
Sets active back to true |
They are provisioned again. Their next sign-in asks them to join again. |
| Creates or changes a group | The group and its members are kept. Groups give no roles or access. |
Some rules keep provisioning from doing more than you meant:
- An owner is never removed. Deactivating an owner keeps them as a member. Their row says "Still a member: provisioning never removes an owner; an owner removes them by hand", and the activity records it.
- A person removed by hand stays out. If an admin removes a provisioned member, or the person leaves, a later sign-in doesn't add them again. Only a deactivation and a reactivation in your identity provider lets them join again.
- Seats. Joining takes a seat. When none is free, accepting the invitation is refused with "this plan has … seat(s) and all are taken; free one or upgrade". Free a seat or change the plan, and the person accepts again.
- No sign-in. Provisioning never signs anyone in. A person still signs in their own way, with their passkey.
Everything SCIM changes is recorded in the organization's activity as "SCIM provisioning".
What the endpoint supports
Path under /api/scim/v2 | Methods |
|---|---|
/Users | GET (list, with a filter), POST |
/Users/{id} | GET, PUT, PATCH, DELETE |
/Groups | GET (list, with a filter), POST |
/Groups/{id} | GET, PUT, PATCH, DELETE |
/ServiceProviderConfig, /ResourceTypes, /Schemas | GET |
- Authentication:
Authorization: Bearer <token>on every request, discovery included. - Filters:
eqonly, joined withand. Users filter onuserName(case-insensitive),externalId,id,emails.value,emails[type eq "work"].value,displayNameandactive(trueorfalse). Groups filter ondisplayNameandid. A group filter onexternalIdis accepted, but answers an empty list. - Pages:
startIndex(from 1) andcount, 100 by default, at most 200. No sorting. - PATCH:
add,replaceandremove, with paths such asname.givenName,emails[type eq "work"].valueand the enterprise extension'surn:…:User:department. At most 1,000 operations. - ETags: every resource has a weak
version,W/"<n>", also sent as theETagheader. - Not supported: bulk, password changes and sorting.
- Limits: 50,000 users and 5,000 groups an organization, and a body of at most 1 MB.
What is kept of a user: userName, externalId, displayName, name.givenName, name.familyName, up to ten emails, title, active, a picture from photos (an https address), a location from addresses (its locality, else formatted or country), and the enterprise extension's department, manager and employeeNumber. Other attributes are accepted and not kept.
Test the token from a terminal before you connect the identity provider:
curl -s https://instruction.md/api/scim/v2/ServiceProviderConfig \
-H "authorization: Bearer $SCIM_TOKEN" curl -s -G https://instruction.md/api/scim/v2/Users \
-H "authorization: Bearer $SCIM_TOKEN" \
--data-urlencode 'filter=userName eq "dana.kim@acme.com"' What an identity provider sends to create a person, and to deactivate them:
curl -s https://instruction.md/api/scim/v2/Users \
-H "authorization: Bearer $SCIM_TOKEN" \
-H 'content-type: application/scim+json' \
-d '{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
"userName": "dana.kim@acme.com",
"externalId": "00u1a2b3c4D5e6F7g8h9",
"name": { "givenName": "Dana", "familyName": "Kim" },
"emails": [{ "value": "dana.kim@acme.com", "type": "work", "primary": true }],
"title": "Support lead",
"active": true,
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "department": "Support" }
}' curl -s -X PATCH https://instruction.md/api/scim/v2/Users/<id> \
-H "authorization: Bearer $SCIM_TOKEN" \
-H 'content-type: application/scim+json' \
-d '{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{ "op": "replace", "path": "active", "value": false }] }' Errors are SCIM error bodies, with scimType where the protocol has one:
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"status": "409",
"scimType": "uniqueness",
"detail": "a user with this userName exists"
} Connect Okta
Add a SCIM app in Okta
In the Okta Admin Console, create an app integration with SCIM provisioning, or open the one you use for instruction.md, and turn on provisioning (General ▸ Provisioning: SCIM).
Set the connection
Under Provisioning ▸ Integration: SCIM connector base URL is
https://instruction.md/api/scim/v2, Unique identifier field for users isuserName, Authentication Mode is HTTP Header, and the bearer token is your SCIM token. Turn on Push New Users, Push Profile Updates and, if you want groups, Push Groups. Choose Test Connector Configuration.Turn on what Okta may do
Under Provisioning ▸ To App, turn on Create Users, Update User Attributes and Deactivate Users. Then assign people or groups to the app.
Connect Microsoft Entra ID
Add an enterprise application
In the Microsoft Entra admin center, open Enterprise applications, add a non-gallery application of your own, or open the one you use for instruction.md.
Set the admin credentials
Under Provisioning, set Provisioning Mode to Automatic. Tenant URL is
https://instruction.md/api/scim/v2and Secret Token is your SCIM token. Choose Test Connection.Start provisioning
Keep the default attribute mappings, assign users or groups, and start provisioning. Entra ID pushes changes on its own cycle, about every 40 minutes.
Entra ID deactivates a person with a PATCH of active, which is supported, and its default mappings use only the attributes listed above.
Pull a people directory
Plans On Pro, Team, and Enterprise
A directory is a list of people that writers can name: as they type @, its people are offered with their picture and job title, and Preview shows who each one is and whether they still work here. instruction.md keeps names and job details only: id, name, email, job title, team, manager, picture, location, whether they are still there, and up to eight extra fields you map. A directory's people never become members.
Add one
In Integrations ▸ Directories ▸ Add a directory, choose Where your people are, give its sign-in, and choose Add it. Its people are pulled at once.
Kind (type) |
Where it reads | Its sign-in, used for this one pull |
|---|---|---|
Okta (okta) |
GET /api/v1/users at your Okta address, 200 a page |
An API token (read-only is enough), sent as SSWS <token> |
Microsoft Entra ID (entra) |
Microsoft Graph /v1.0/users, with each person's manager, 999 a page |
A tenant with an app's client id and secret (the app needs User.Read.All), or a Graph access token |
Google Workspace (google) |
The Admin SDK directory's users, 500 a page, all domains or one (domain) |
An access token that may read your users |
Workday (workday) |
A report's address (Workday RaaS, read as JSON) | The integration user and its password, sent as Basic |
A SCIM server (scim) |
Its /Users, 100 a page |
A token, if it asks for one |
Another address (json) |
Any https address that answers a list of people as JSON, through a mapping |
A token, if it asks for one; tokenHeader names another header than Authorization: Bearer |
A file (csv, json) |
A CSV with a header row, or a JSON list, uploaded | None |
{
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C",
"type": "okta",
"url": "https://acme.okta.com",
"token": "<an Okta API token>"
} {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C",
"type": "entra",
"tenant": "acme.onmicrosoft.com",
"clientId": "<application (client) id>",
"clientSecret": "<client secret>"
} The credential is never kept. It is taken out of the call before anything else reads it, sent only to the directory's own address (Entra ID's secret only to login.microsoftonline.com), and gone when the call ends. Neither a receipt, an error nor the audit holds it; the audit says only that a pull was made with a token. An address that carries a credential in its query, such as ?api_key=, is refused: give it as token.
Map the fields
A file or an address whose names differ from the common ones needs a mapping: id, name, email, title, department, manager, picture, active, location, and for an address list (where the list is) and next (where the next page's address is). Each is a JSON path such as work.email or data[0].id, or a CSV column. extra maps up to eight more fields, by the label to show.
A CSV's columns are matched by their names, whatever their case and spacing: Employee ID, Full name, Work email, Job title, Team, Manager email, Photo URL, Status and Office need no mapping. A manager given as an email is matched to that person. A status such as terminated, inactive or false marks someone as no longer there. Without an id column, the email is the id.
Employee ID,Full name,Work email,Job title,Team,Manager email,Photo URL,Status,Office
1001,Dana Kim,dana.kim@acme.com,Support lead,Support,lee.park@acme.com,https://cdn.acme.com/people/1001.jpg,active,Lisbon
1002,Lee Park,lee.park@acme.com,Head of support,Support,,https://cdn.acme.com/people/1002.jpg,active,Lisbon
1003,Sam Ortiz,sam.ortiz@acme.com,Support agent,Support,dana.kim@acme.com,,terminated,Remote A file whose columns have other names, with its mapping:
Staff no,Person,Mail,Role,Unit
E-17,Dana Kim,dana.kim@acme.com,Support lead,Support {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C",
"type": "csv",
"title": "HR export",
"fileName": "people.csv",
"document": "Staff no,Person,Mail,Role,Unit\nE-17,Dana Kim,dana.kim@acme.com,Support lead,Support\n",
"mapping": { "id": "Staff no", "name": "Person", "email": "Mail", "title": "Role", "department": "Unit" }
} An address with its own shape, its token in another header:
{
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C",
"type": "json",
"url": "https://hr.acme.com/api/people",
"token": "<a token>",
"tokenHeader": "X-API-Key",
"mapping": { "list": "data.people", "next": "links.next", "id": "staffId", "name": "fullName", "email": "work.email", "manager": "managerId", "extra": { "Cost centre": "finance.costCentre" } }
} Every argument of orgs_people_directories_add
| Argument | Required | What it is |
|---|---|---|
orgId | yes | The organization (org_…). |
type | yes | Where the people are. |
url | Its https address: the Okta organization, the Workday report, the SCIM base URL, the JSON address. | |
document | A CSV or JSON file's text (an upload), at most 5 MB. | |
fileName | An upload's file name. | |
title | Its name (default: its type's). | |
tenant | Entra ID: the tenant (its id or domain), with clientId and clientSecret. | |
domain | Google Workspace: only this domain (default: the whole account). | |
mapping | JSON and CSV: where each field is, {list, next, id, name, email, title, department, manager, picture, active, location, extra: {label: path}}: a JSON path of names and indexes, or a CSV column. | |
token | The credential for this one pull, never kept: an API token or a bearer token. | |
tokenHeader | JSON and SCIM: the header the token goes in (default: Authorization: Bearer). | |
username | Workday: the integration user, with password (Basic). | |
password | Workday: its password, used once and never kept. | |
clientId | Entra ID: the app's client id, with clientSecret and tenant (client credentials). | |
clientSecret | Entra ID: the app's client secret, used once and never kept. | |
idempotencyKey | Any unique string: the call sent again with it answers its first result. |
Pull it again, hide it, remove it
- Pull again reads the directory again now. A directory that needed a sign-in asks for it again, because it was never kept. An uploaded file is pulled again by uploading it again. People no longer found are kept and marked as no longer there, and come back if they reappear.
- A pull in the background (
orgs_integrations_sync, which queues it and answers at once) reads a directory that needs no sign-in. A directory that needs one, or an uploaded file, is left as last pulled, with the note "Pull again needs your token" or "Uploaded: upload the file again to pull it again". Directories are not pulled on a schedule. - Offered as you write (
orgs_people_directories_set) offers a directory's people as members type@, or hides them. Hidden people still resolve where they are already named. This organization can be hidden too. - Remove (
orgs_integrations_remove) deletes the directory and its people. Instructions keep the names they wrote, and those people show as unknown. A directory of the same kind added again gets the same key back, so the references written before resolve again.
Limits: 20,000 people a directory (the first ones are kept and the pull says so), a file of at most 5 MB, and 100 integrations an organization, directories included.
| Tool | What it does | Arguments |
|---|---|---|
orgs_people_directories_list | List people directories | orgId |
orgs_people_directories_add | Add a people directory | orgId, type, url (optional), document (optional), fileName (optional), title (optional), tenant (optional), domain (optional), mapping (optional), token (optional), tokenHeader (optional), username (optional), password (optional), clientId (optional), clientSecret (optional), idempotencyKey (optional) |
orgs_people_directories_pull | Pull a people directory again | orgId, integrationId, document (optional), fileName (optional), token (optional), tokenHeader (optional), username (optional), password (optional), clientId (optional), clientSecret (optional) |
orgs_people_directories_set | Offer or hide a directory's people | orgId, directory, offered |
orgs_integrations_sync | Pull an integration again | orgId, integrationId |
orgs_integrations_remove | Remove an integration | orgId, integrationId |
How person references resolve
An instruction names a person with a typed reference. The editor writes it when you pick someone after @:
Escalate refunds over €500 to :person[Dana Kim]{ref=person://okta/00u1a2b3c4D5e6F7g8h9}. | Reference | Who it names |
|---|---|
principal://usr_… |
A member of the organization, including a provisioned person who joined. Someone who left is still named, marked as departed. |
person://workspace/<id> |
A person SCIM provisioned who hasn't joined yet. Once they join, it resolves to them as a member. |
person://<key>/<id> |
A person of an added directory. The key is the directory's: its kind, such as okta, then okta-2 for a second one. The id is the directory's own, percent-encoded. |
orgs_people_get resolves up to 100 references at once. The ones it doesn't know are in missing. orgs_people_search finds people by words in their name, email, job title, team or location, and answers the reference to write for each. Only offered directories are searched unless directory names one, and departed people only with include: ["departed"]. Members see each person's details; only owners and admins see members' emails.
{ "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C", "refs": ["principal://usr_01JX7Q3B5D7F9H1K3M5P7R9T1V", "person://workspace/01jxb2c3d4e5f6g7h8j9k0m1n2", "person://okta/00u1a2b3c4D5e6F7g8h9"] } {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C",
"orgName": "Acme",
"people": [
{ "ref": "person://okta/00u1a2b3c4D5e6F7g8h9", "directory": { "id": "itg_01JXB0…", "key": "okta", "type": "okta", "title": "Okta" },
"id": "00u1a2b3c4D5e6F7g8h9", "name": "Dana Kim", "title": "Support lead", "department": "Support",
"manager": { "id": "00u9z8y7x6", "ref": "person://okta/00u9z8y7x6", "name": "Lee Park" },
"active": true, "state": "active" },
…
],
"missing": []
} | Tool | What it does | Arguments |
|---|---|---|
orgs_people_search | Search people | orgId, query (optional), directory (optional), include (optional), limit (optional), cursor (optional) |
orgs_people_get | Resolve people | orgId, refs |
Nothing about a person is ever public: a reader who isn't a member of the organization sees the label the writer typed, not the person.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
SCIM 401, unknown or revoked token |
The token is wrong, revoked or past its keepOldHours. |
Make a new token and paste it into your identity provider. |
SCIM 403, SCIM provisioning needs the Team plan or above |
The organization's plan has no SCIM. | Change the plan; the tokens work again at once. |
SCIM 409, a user with this userName exists |
Another provisioned user has this userName. |
Match the existing user (filter on userName) instead of creating one. |
SCIM 400, This filter isn't supported: use attr eq "value" (and …) |
The filter uses an operator other than eq. |
Filter with eq and and only. |
SCIM 400 with scimType: tooMany |
The organization has 50,000 users or 5,000 groups. | Deprovision people or groups you don't need. |
an organization has at most 5 working SCIM tokens; revoke one first |
5 tokens work already. | Revoke one you don't use. |
only an owner makes or rotates SCIM tokens |
An admin asked. | Ask an owner. |
| A provisioned person didn't join | They haven't accepted the invitation, their sign-in's email doesn't match, or no seat is free. | Check their row in This organization: it shows the reason. |
The directory asks for sign-in (HTTP 401): add its token to pull it |
The address needs a credential. | Give it in the sign-in fields, or token. |
The directory refused the credential (HTTP 403) |
The credential is wrong or can't read users. | Check its permissions, such as Entra ID's User.Read.All. |
the address holds a credential (…) |
The address has a token in its query. | Remove it from the address and give it as the token. |
adding a people directory needs the Pro plan or above |
The plan has no directories. | Change the plan. |
| Still stuck | Report it with the message and the directory's kind. |
Questions
Should I connect Okta or Entra ID with SCIM or as a directory?
SCIM if your identity provider should decide who is in the organization: it adds and removes members by itself. A directory if writers only need to name people, such as the whole company, without giving them accounts. You can use both.
Does SCIM give people roles or access to workspaces?
No. A provisioned person who joins is a member, with the organization's default workspace role if it has one. Groups are kept, but give no roles. Change roles in Settings ▸ People.
Does a provisioned person take a seat?
Not until they join. A person provisioned but not signed in is listed and can be named, without a seat.
Is a directory's credential stored?
No. It is used for one pull and dropped. Pull again asks for it again, and a background pull skips a directory that needs one.
What happens to an instruction that names someone who left?
It keeps the reference. Preview shows the person marked as no longer at the organization. Remove or replace the reference in the draft and publish a new version.