Esta página aún no está traducida.

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:admin scope (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.

What your identity provider asks for
Base URL:      https://instruction.md/api/scim/v2
Authorization: Bearer imdscim_<the token>

Make a token

  1. 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.

  2. Choose Make a token

    An owner sees Make a token (or Make another token when one works already). Admins see Owners.

  3. 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:

orgs_scim_tokens_create arguments
{ "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C", "label": "Okta" }
The answer
{
  "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>"
}
ToolWhat it doesArguments
orgs_scim_tokens_listList SCIM tokensorgId
orgs_scim_tokens_createMake or rotate a SCIM tokenorgId, label (optional), replaces (optional), keepOldHours (optional), idempotencyKey (optional)
orgs_scim_tokens_revokeRevoke a SCIM tokenorgId, 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_create with replaces and keepOldHours (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.
Rotate, keeping the old token for 24 hours
{
  "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/v2Methods
/UsersGET (list, with a filter), POST
/Users/{id}GET, PUT, PATCH, DELETE
/GroupsGET (list, with a filter), POST
/Groups/{id}GET, PUT, PATCH, DELETE
/ServiceProviderConfig, /ResourceTypes, /SchemasGET
  • Authentication: Authorization: Bearer <token> on every request, discovery included.
  • Filters: eq only, joined with and. Users filter on userName (case-insensitive), externalId, id, emails.value, emails[type eq "work"].value, displayName and active (true or false). Groups filter on displayName and id. A group filter on externalId is accepted, but answers an empty list.
  • Pages: startIndex (from 1) and count, 100 by default, at most 200. No sorting.
  • PATCH: add, replace and remove, with paths such as name.givenName, emails[type eq "work"].value and the enterprise extension's urn:…:User:department. At most 1,000 operations.
  • ETags: every resource has a weak version, W/"<n>", also sent as the ETag header.
  • 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:

The service provider's configuration
curl -s https://instruction.md/api/scim/v2/ServiceProviderConfig \
  -H "authorization: Bearer $SCIM_TOKEN"
Find a user by userName
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:

Create a user
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" }
  }'
Deactivate a user
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:

A userName that is taken
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "a user with this userName exists"
}

Connect Okta

  1. 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).

  2. Set the connection

    Under Provisioning ▸ Integration: SCIM connector base URL is https://instruction.md/api/scim/v2, Unique identifier field for users is userName, 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.

  3. 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.

Okta's SCIM connection to instruction.md.

Connect Microsoft Entra ID

  1. 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.

  2. Set the admin credentials

    Under Provisioning, set Provisioning Mode to Automatic. Tenant URL is https://instruction.md/api/scim/v2 and Secret Token is your SCIM token. Choose Test Connection.

  3. 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
orgs_people_directories_add: Okta
{
  "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C",
  "type": "okta",
  "url": "https://acme.okta.com",
  "token": "<an Okta API token>"
}
orgs_people_directories_add: Entra ID with an app's client credentials
{
  "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.

people.csv, matched by its column names
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:

people.csv
Staff no,Person,Mail,Role,Unit
E-17,Dana Kim,dana.kim@acme.com,Support lead,Support
orgs_people_directories_add with a mapping
{
  "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:

orgs_people_directories_add: any JSON address
{
  "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
ArgumentRequiredWhat it is
orgIdyesThe organization (org_…).
typeyesWhere the people are.
urlIts https address: the Okta organization, the Workday report, the SCIM base URL, the JSON address.
documentA CSV or JSON file's text (an upload), at most 5 MB.
fileNameAn upload's file name.
titleIts name (default: its type's).
tenantEntra ID: the tenant (its id or domain), with clientId and clientSecret.
domainGoogle Workspace: only this domain (default: the whole account).
mappingJSON 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.
tokenThe credential for this one pull, never kept: an API token or a bearer token.
tokenHeaderJSON and SCIM: the header the token goes in (default: Authorization: Bearer).
usernameWorkday: the integration user, with password (Basic).
passwordWorkday: its password, used once and never kept.
clientIdEntra ID: the app's client id, with clientSecret and tenant (client credentials).
clientSecretEntra ID: the app's client secret, used once and never kept.
idempotencyKeyAny 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.

ToolWhat it doesArguments
orgs_people_directories_listList people directoriesorgId
orgs_people_directories_addAdd a people directoryorgId, 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_pullPull a people directory againorgId, integrationId, document (optional), fileName (optional), token (optional), tokenHeader (optional), username (optional), password (optional), clientId (optional), clientSecret (optional)
orgs_people_directories_setOffer or hide a directory's peopleorgId, directory, offered
orgs_integrations_syncPull an integration againorgId, integrationId
orgs_integrations_removeRemove an integrationorgId, integrationId

How person references resolve

An instruction names a person with a typed reference. The editor writes it when you pick someone after @:

A person in an instruction
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.

orgs_people_get arguments
{ "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C", "refs": ["principal://usr_01JX7Q3B5D7F9H1K3M5P7R9T1V", "person://workspace/01jxb2c3d4e5f6g7h8j9k0m1n2", "person://okta/00u1a2b3c4D5e6F7g8h9"] }
The answer
{
  "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": []
}
ToolWhat it doesArguments
orgs_people_searchSearch peopleorgId, query (optional), directory (optional), include (optional), limit (optional), cursor (optional)
orgs_people_getResolve peopleorgId, 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.

Last checked against the product:

Was this page helpful? Report a problem