Organizations

Organizations let you group users within an environment. Users join organizations through memberships and can be assigned organization-level roles.

Creating an Organization

curl -X POST https://acme-test.paylent.com/api/organizations \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "organization",
      "attributes": {
        "name": "Acme Corp"
      }
    }
  }'

Memberships

A membership links a user to an organization. Each user can only have one membership per organization.

Adding a Member

curl -X POST https://acme-test.paylent.com/api/memberships \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "membership",
      "attributes": {},
      "relationships": {
        "user": { "data": { "type": "user", "id": "USER_ID" } },
        "organization": { "data": { "type": "organization", "id": "ORG_ID" } }
      }
    }
  }'

Organization Roles

Memberships can be assigned roles (via membership_role), allowing organization-level permission structures separate from environment-level roles.

Invitations

Invite users to join an organization by email. Invitations include:

• Target email address
• Role IDs to assign on acceptance
• Expiry timestamp
• Invitation status tracking

Sending an Invitation

curl -X POST https://acme-test.paylent.com/api/invitations \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "invitation",
      "attributes": {
        "email": "[email protected]",
        "role_ids": ["ROLE_ID_1", "ROLE_ID_2"]
      },
      "relationships": {
        "organization": { "data": { "type": "organization", "id": "ORG_ID" } }
      }
    }
  }'

Invitation Lifecycle

Status	Description
pending	Invitation sent, awaiting response
accepted	User accepted and joined the organization
declined	User declined the invitation
revoked	Invitation was revoked by an admin

Only one pending invitation can exist per email per organization. Invitations can be accepted or declined via dedicated endpoints:

POST /invitations/:id/accept
POST /invitations/:id/decline