Members & Clients

Provision the people on your account from your own backend. All requests need the X-Integration-Token header, see the overview for authentication and base URL.

Roles in one line: members are your team (they manage feedback), and clients are external reviewers (they leave feedback on projects they are invited to). Details in Clients.

Members

List members

curl -H "X-Integration-Token: $TOKEN" \
  "https://www.simplecommenter.com/api/external/members"

Returns { members: [...] } including the account owner. Add ?domainId=sc_xxx and each member also gets an assigned flag for that project.

Add a member

curl -X POST -H "X-Integration-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@acme.com", "name": "Dev", "role": "team", "domainId": "sc_xxx"}' \
  "https://www.simplecommenter.com/api/external/members"

role is "user" (workspace admin) or "team" (team lead). domainId is optional: when present, the new member is assigned to that project right away. New members log in via magic link, no password needed.

Company login and API provisioning

POST /api/external/members creates the same workspace membership used by Company login (SSO). It creates one member per request; your backend can send a request for each employee to onboard a team of 100 without entering them manually. The token needs the write action. There is no bulk-array request format or SSO-approval parameter.

1. Create each member with the email their company identity provider supplies. Use role: "team" unless they need workspace-admin permissions, and set their project assignments intentionally.
2. The workspace owner opens Workspace settings → Company login, refreshes the page, and approves the new members under Approve and test.
3. Share the workspace's company-login link. Approved members can authenticate with the identity provider without a separate registration or Simple Commenter password, once the SSO connection is active.

On first login, the signed provider email is matched to an approved member in that workspace. Later logins use the linked provider identity. Creating a member does not automatically approve SSO, sign them in, create a paid subscription, or merge accounts in other workspaces. An unknown or unapproved person is refused access; automatic membership creation on first login and SCIM directory synchronization are not implemented.

For repeat runs, list existing members first and skip emails already present. A duplicate member email returns 400; creation is not an idempotent upsert. If a request times out, check whether the member was created before retrying. When no domainId is supplied, project assignment follows the workspace's default for new members, which may grant access to every project.

Assign or unassign a member on a project

curl -X PUT -H "X-Integration-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memberId": "MEMBER_ID", "domainId": "sc_xxx", "assigned": true}' \
  "https://www.simplecommenter.com/api/external/members"

Remove a member

curl -X DELETE -H "X-Integration-Token: $TOKEN" \
  "https://www.simplecommenter.com/api/external/members?memberId=MEMBER_ID"

Clients

List clients on a project

curl -H "X-Integration-Token: $TOKEN" \
  "https://www.simplecommenter.com/api/external/clients?domainId=sc_xxx"

Create or sync a client

curl -X POST -H "X-Integration-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domainId": "sc_xxx", "email": "jane@customer.com", "name": "Jane", "autoApprove": true}' \
  "https://www.simplecommenter.com/api/external/clients"

Idempotent: if the email already exists on the project, the existing client is returned (and the name updated if it changed).

Approve or revoke a client

curl -X PUT -H "X-Integration-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domainId": "sc_xxx", "email": "jane@customer.com", "approved": true}' \
  "https://www.simplecommenter.com/api/external/clients"

Remove a client

curl -X DELETE -H "X-Integration-Token: $TOKEN" \
  "https://www.simplecommenter.com/api/external/clients?domainId=sc_xxx&email=jane@customer.com"

Client login tokens

Mint a widget login token for an approved client, valid 30 days. This is the primitive the WordPress plugin uses for auto-login; with the JS API you normally do not need it, since a verified identify mints the token for you.

curl -X POST -H "X-Integration-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domainId": "sc_xxx", "email": "jane@customer.com"}' \
  "https://www.simplecommenter.com/api/external/client-token"

Returns { token, email, name }. Store the token in the visitor's browser under the simpleCommenterUserData localStorage key before the widget loads, or pass it via the ?simple-commenter-token= URL parameter.