Organizations and members

An organization is a customer account in your product: a team, a workspace, a company. Everything inside it belongs to exactly one organization.

A member is someone’s place in an organization. A member is either a person or a service account, and has a role (when roles are on) and a status.

People

A person is created the first time they sign in, from your identity provider’s issuer and subject. People are private: customers can’t list or search them. Your staff can, through the operator gateway.

A person has a display name, which they can override in each organization. Someone can belong to many organizations; GET /user/memberships lists theirs.

Creating an organization

POST /user/organizations
Authorization: Bearer <user token>

{ "name": "Northwind" }

The person who creates it becomes its first member, with the deployment’s creator role.

Adding people

Two ways, both producing an active member right away:

• Invites. POST /org/invites returns a token. Send it however you like (Plat5 sends no email). The person redeems it with POST /user/invites/redeem after signing in. Invites are single-use by default. Set a number of uses, or no limit for a shareable join link. They expire after seven days unless you choose otherwise.
• By identity-provider subject. POST /org/members with the person’s issuer and subject at your IdP, which your backend already knows. Plat5 creates the person if they haven’t signed in yet.

Service accounts

A service account is a member with API keys and no person behind it. Use one for a customer’s integration or your own automation. It belongs to one organization and has its own role, independent of whoever created it.

POST /org/service-accounts
POST /org/service-accounts/{service_account_id}/api-keys

Suspending and removing

• Suspend is reversible. A suspended member’s credentials stop working until they’re reactivated.
• Remove is final. Their keys are revoked and their sessions deleted. Adding the person again creates a new member.

A removed member can still be looked up by id at the organization’s address, as a display name and status: removed, so your product can show “Alice (former member)” on things she wrote.

An organization always keeps at least one member, and at least one member with the creator role. A person can’t delete their account while they’re the last member or last creator-role holder of an organization; they hand it off or delete the organization first.

Lifecycle events

Plat5 records when organizations and members are created and removed, in the same transaction as the change. Your services can read the feed to set up or clean up their own data:

GET /internal/lifecycle-events?starting_after=<id>

Events: organization.created, organization.deleted, member.created, member.removed.

More: identity.md.