Skip to main content

Organization API Overview

The Organization API is the org-scoped external surface on api.propper.ai. It resolves organization-level state from your access token, so the organization is never passed in the path.

↓ OpenAPI JSON

Endpoints​

Organization​

  • GET /v1/org: read the calling organization's profile (name, data residency, timestamps). Requires the org:read scope.
  • GET /v1/org/entitlements: resolve the calling organization's derived entitlement verdict. The response projection is selected with the view query parameter. Platform-only (see below).

Members​

Members are addressed by user identifier, the same value the roster returns as user.id.

  • GET /v1/org/members: list the calling organization's members with their role and status, paginated. Requires the users:read scope.
  • POST /v1/org/members/invite: invite an email address to join the organization and send the invitation email. Requires the users:write scope.
  • PUT /v1/org/members/{userId}: change a member's role. Requires the users:write scope.
  • DELETE /v1/org/members/{userId}: remove a member and end their sessions for this organization. Requires the users:write scope.
  • GET /v1/org/members/{userId}/capabilities: read the permissions a member's role grants. Requires the users:read scope.
  • DELETE /v1/org/invitations/{invitationId}: withdraw a pending invitation. Requires the users:write scope.

Member preferences​

  • GET /v1/org/users/{userId}/settings: read a member's interface preferences. Requires the users:read scope.
  • PUT /v1/org/users/{userId}/settings: update a member's interface preferences. Requires the users:write scope.

Preferences are held separately per organization, so a person who belongs to several carries a different set in each.

Assignable roles​

Invitations and role changes accept viewer, author, publisher, approver, and org_admin. Any other value is rejected.

An organization always keeps at least one administrator: removing or demoting the last one is refused, since it would leave nobody able to administer the organization or to undo the change.

Authentication​

OAuth 2.0 Bearer token; the organization is resolved from the token. Customer integrations request the org:read scope (organization profile), the users:read scope (membership, capabilities, and preferences), and the users:write scope (the membership lifecycle and preference writes); all three can be assigned to client applications you create and manage in your organization settings. users:write does not imply users:read, so request both if your integration reads and writes. Individual endpoints may carry stricter, platform-only scope requirements, so check each endpoint's scope before integrating: the entitlement verdict projection, view=salesforce below, is platform-only and is NOT reachable with org:read (it requires the platform-reserved org:entitlements:read scope, which is not customer-requestable).

Entitlement verdict projections​

The view query parameter selects the projection of the entitlement verdict.

view=salesforce​

GET /v1/org/entitlements?view=salesforce returns the verdict shaped for the Salesforce connector. This projection is platform-only: the path is callable exclusively by Propper-generated Salesforce client applications, gated on the platform-reserved org:entitlements:read scope (with entitlements:read as its legacy alias). Neither is a customer-requestable scope, so customer-created applications cannot call it.