Update a membership

PATCH /v1/organizations/{org_id}/memberships/{membership_id} · permission organizations:write

Changes the membership's role_ids (the full set of manually assigned roles) or expires_at with a JSON merge patch (Content-Type: application/merge-patch+json). Both fields may change in the same request; they are applied in a single transaction, so either both are written or neither is, and one organization_membership.updated audit record is written. expires_at must be in the future and at most 365 days after the membership was created; null removes the end date. role_ids: null has no effect. Role rules are those of PUT …/roles. A field equal to its current value is not written. The write is audited as organization_membership.updated.

Request

Field Type Required Description
org_id path yes Organization ID (org_…).
membership_id path yes Membership ID (mem_…).
If-Match header no Current ETag; if given it must match (412) and pins the write to that version.
role_ids string[] no Full set of manually assigned role IDs (rol_…), at most 50.
expires_at string | null no End of the membership (RFC 3339); null removes it.

Response

200 OK with the updated membership and its ETag.

{
  "id": "mem_01j9xn5p9s0t4v6w8x0y2z4a6c",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "user_id": "usr_01j9xh2k6p7q1r3s5t7v9w1x3y",
  "status": "active",
  "source": "admin_api",
  "reason": null,
  "roles": [
    {
      "role_id": "rol_01j9xr7s1t2w6x8y0z2a4b6c8e",
      "source": "admin_api",
      "assigned_at": "2026-10-12T09:31:00.123456Z"
    }
  ],
  "expires_at": "2027-01-01T00:00:00Z",
  "created_at": "2026-10-12T09:31:00.123456Z",
  "activated_at": "2026-10-12T09:31:00.123456Z",
  "suspended_at": null,
  "removed_at": null,
  "updated_at": "2026-10-12T10:00:00Z",
  "version": 2
}

Errors

HTTP code When
404 not_found The membership does not exist in this organization.
403 role_not_assignable A role is not an environment role or a role of this organization.
409 last_org_admin The change would leave the organization without an active admin.
412 precondition_failed If-Match does not match the current version.
415 unsupported_media_type The body is not application/merge-patch+json.
422 validation_failed expires_at is out of range or the membership is removed (invalid_state), or a value is invalid.
401 unauthenticated The credential is missing, invalid or revoked.
403 insufficient_permissions The credential lacks the required permission. Assigning a privileged (is_privileged) role also requires roles:write; without it nothing is written and required_permissions lists both permissions.
429 rate_limited The rate limit was exceeded; retry after the Retry-After period.
503 service_unavailable A dependency is temporarily unavailable; retry after the Retry-After period.

Example

curl -i -X PATCH "https://api.eu.keenauth.com/v1/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a/memberships/mem_01j9xn5p9s0t4v6w8x0y2z4a6c" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"expires_at":"2027-01-01T00:00:00Z"}'

Personal data

This endpoint carries personal data: organization memberships and invitations. Personal data in the KeenAuth APIs describes what is stored, how long it is kept and how it is deleted. Do not send special categories of personal data (health, biometric data, religion, political opinions, sexual orientation) in any field.