Organizations

Multi-tenant workspaces — the Organization model, membership, signup tokens, signup emails, domain auto-join, and organization-scoped permissions.

Overview

Organizations are the top-level grouping for teams working together in Bosca. Each Organization has its own members, permissions, and content. Organizations extend PermissibleEntity, so all standard permission checks apply, and they expose ContentItem for inclusion in collections.

Organization Model

kotlin
Every Organization has an associated Profile (profileId) that serves as its public identity — name, logo, description, and other attributes.

Membership

Members are Principals linked to an Organization. Membership is stored as a simple join record:

kotlin

Permissions within an Organization are granted to groups, not individual members. Members inherit access through their group memberships.

Signup Mechanisms

Bosca supports three ways to add members to an Organization:

1. Signup Tokens

Time-limited invitation strings tied to a specific group. The recipient redeems the token to join the Organization and be assigned to the linked group.

kotlin

The signup token input identifies which built-in group new members should land in via the OrganizationSignupGroupType enum (ADMINISTRATORS, USERS, UNKNOWN); the server resolves it to a concrete group and stores the resulting groupId on the token.

graphql

2. Signup Emails

Pre-authorize specific email addresses. When a user signs up with a matching email, they are added to the Organization and assigned to the group implied by the OrganizationSignupGroupType.

kotlin
graphql

3. Domain Auto-Join

Link an email domain to an Organization. When autoJoin is true, any user signing up with a matching email domain is automatically added.

kotlin
graphql
Domain auto-join is useful for enterprise deployments where all employees share a corporate email domain. Combined with OAuth2 SSO, it enables zero-friction onboarding.

Organization Permissions

Permissions are granted at the Organization level to groups. Each permission record maps a group to a PermissionAction:

kotlin

Since Organization extends PermissibleEntity, the standard decision chain applies — public access flags, group checks, and role-based fallbacks all work the same way.

Membership Mutations

Member management requires MANAGE permission on the Organization:

graphql

Creating an Organization

organizations.add is intentionally open so that signup flows can create an organization and its linked profile in one step:

graphql

How It Fits Together

  • Principal (security identity) → is a Member of an Organization
  • Organization → has a linked Profile (public identity)
  • Groups → receive permission grants on the Organization; members inherit access through them
  • Signup mechanisms → control how new Principals are routed into the Organization and into a specific group