Organisations

In a multi-tenant app, data belongs to organisations. People join them as members with one role each, invite others by email, and reach an organisation's rows only while they are members. Decision: ADR-0048.

Create a multi-tenant app#

aps new acme-api --preset full --tenancy multi

creating acme-api in ./acme-api
preset full · tenancy multi · library ../apistock

✓ ran go mod tidy
✓ initialised git

created acme-api

Start it with aps dev. Seed data creates admin@example.com with a personal workspace holding three example projects, so GET /v1/orgs and GET /v1/orgs/{orgId}/projects return data straight away.

Roles#

Every member has exactly one role.

• Nobody gives, changes or removes a role above their own, and only owners manage owners.
• The last owner can't leave, be demoted or be removed (409 last_owner). Promote another member to owner first.
• Add roles for your product, such as a read-only viewer, in declareOrgPermissions in internal/app/permissions.go.

Personal workspaces#

Every account gets a workspace called "Personal" when it is created: at registration, at the first Google or Apple sign-in, and with create-user. The account owns it. A personal workspace can't be left, deleted on its own or shared by invitation; teams create an organisation instead. It is deleted with the account.

Invitations#

Add an org-scoped resource#

In a multi-tenant app, aps gen resource scopes resources to organisations by default:

aps gen resource Invoice number:string:unique 'status:enum(draft,sent,paid)'

It writes endpoints under /v1/orgs/{orgId}/invoices, declares invoices.invoice.read and invoices.invoice.write, and adds one line at //aps:anchor org-permissions so every organisation role holds them. Change which roles hold them in declareOrgPermissions.

Check membership in a use case#

Every organisation operation starts by calling orgs.RequireMember. It is a function rather than middleware: the organisation ID is only known after routing, and a check inside the use case also protects jobs and commands that call it.

func (s *Service) Get(ctx context.Context, orgID orgs.ID, id string) (Invoice, error) {
	ctx, _, err := orgs.RequireMember(ctx, s.memberships, s.catalog, orgID, PermRead)
	if err != nil {
		return Invoice{}, err // 404 org_not_found, or 403 forbidden
	}
	return s.store.SelectInvoice(ctx, orgID, id)
}

The membership is read on every call, so removing a member takes effect on their next request. Someone who isn't a member gets the same 404 as for an organisation that doesn't exist, so organisation IDs can't be probed.

Four layers of isolation#

One mistake in one layer shouldn't leak data. Each layer is checked by a test in your app.

Deleting organisations and accounts#

• An owner deletes an organisation with DELETE /v1/orgs/{orgId}. Members lose access at once. An owner can restore it with POST /v1/orgs/{orgId}/restore until the orgs.deleted_org_retention period ends; then the orgs_purge job removes it with every org-scoped row.
• Deleting an account is refused with 409 sole_owner while the account is the only owner of an organisation with other members. The response lists those organisations. Organisations where the account is the only member are deleted with it.

Runtime settings#

Error codes#