App Memberships

Membership endpoints are service-to-service. Call them with a client-credentials access token (see OAuth2 client credentials), not a user token. The acting app is taken from the token's client_id (the JWT subject), which is signed and cannot be forged.

Two scopes govern access:

An app can only read and write memberships for its own client_id. A clientId in a request body is optional, and if present it must equal the calling client; the server always writes the membership for the caller, never for the value in the body. Attempting to act for another client returns 403 FORBIDDEN.

Returns the memberships owned by the calling app. Requires the app:memberships:read scope.

Query parameters

Grants an app membership to a ZB ID identity for the calling app. Requires the app:memberships:write scope. Identify the subject by userId or email (at least one is required). Returns 404 if no matching identity exists.

Request body

Revokes a membership owned by the calling app. Requires the app:memberships:write scope. Returns 204 No Content on success, or 404 Not Found if the membership does not exist or is not owned by the calling app.

The routes above are scoped to the calling app: a client-credentials token's subject is its client_id, so an app can only read and write its own roll. That leaves nobody able to seed the first member of a brand-new app, because until someone is a member there is no app to act for.

The routes under /v1/admin/memberships close that gap. They are the administrator's cross-app path: one call can put an identity into any registered app, or take them out of it, whichever app owns the row.

They differ from /v1/memberships in three ways:

Who is recorded as the grantor

Never the request body. grantedBy is the acting administrator's ZB ID user id, taken from the token's sub claim, and grantedByClient is the app the token was minted for, taken from its aud claim. A client-credentials caller has no human behind it, so grantedBy is left null.

Every call to these two writes is recorded in the auth audit log as ADMIN_MEMBERSHIP_GRANTED or ADMIN_MEMBERSHIP_REVOKED, on success and on failure. The audit row is written against the subject whose membership changed, so the change appears on that person's own trail; the acting administrator travels alongside it in the row's metadata.

Returns one page of the membership roll for a single app, newest first, with each row resolved back to the ZB ID identity behind it. Requires admin:users.

Query parameters

Response

A paged envelope of items, page, size and total, where total is the count of all matching rows rather than the page size. Each item carries id, userId, email, fullName, role, status and createdAt. email and fullName are null when the membership points at an identity that no longer exists.

Grants a membership to any identity on any registered app. Requires admin:users.

The call is idempotent per (user, app, role). Re-granting a membership that already exists re-activates a revoked row and re-stamps who granted it, rather than failing, and still answers 201.

Request body

There is deliberately no grantedBy field. Both provenance columns come from the verified token, so a caller cannot dictate who the audit trail says made the grant.

Status codes

Revokes a membership by id, whichever app owns it. Requires admin:users. The row is set to REVOKED rather than deleted, so the grant and revoke history survives.

This is the administrator's path and is separate from DELETE /v1/memberships/{id} on purpose. That one still refuses to touch a membership belonging to another client, so an app holding a client-credentials token cannot reach across into someone else's roll.

Status codes