Organization Plugin

The organization plugin provides multi-tenant organization management for Authsome. It handles organization CRUD, member management, team hierarchies, invitation workflows, and organization-scoped roles.

Setup

import (
    "github.com/xraph/authsome"
    "github.com/xraph/authsome/plugins/organization"
)

eng, err := authsome.NewEngine(
    authsome.WithStore(store),
    authsome.WithPlugin(organization.New(store, organization.Config{
        PathPrefix: "/v1/auth",
    })),
)

Configuration

Implemented interfaces

Organization CRUD

Create organization

POST /v1/auth/organizations

{
  "name": "Acme Corp",
  "slug": "acme-corp",
  "metadata": {"plan": "enterprise"}
}

Get organization

GET /v1/auth/organizations/:orgId

Update organization

PUT /v1/auth/organizations/:orgId

{
  "name": "Acme Corporation",
  "metadata": {"plan": "enterprise", "seats": 100}
}

Delete organization

DELETE /v1/auth/organizations/:orgId

Member management

Add member

POST /v1/auth/organizations/:orgId/members

{
  "user_id": "ausr_01j9...",
  "role": "admin"
}

List members

GET /v1/auth/organizations/:orgId/members

Update member role

PUT /v1/auth/organizations/:orgId/members/:memberId

{"role": "owner"}

Remove member

DELETE /v1/auth/organizations/:orgId/members/:memberId

Team management

Teams provide sub-grouping within organizations:

Create team

POST /v1/auth/organizations/:orgId/teams

{
  "name": "Engineering",
  "description": "Product engineering team"
}

Add team member

POST /v1/auth/organizations/:orgId/teams/:teamId/members

{"user_id": "ausr_01j9..."}

Invitation system

Invite users to join an organization by email:

Send invitation

POST /v1/auth/organizations/:orgId/invitations

{
  "email": "bob@example.com",
  "role": "member"
}

The engine creates an invitation record and, if the email plugin or notification plugin is registered, sends an invitation email automatically.

Accept invitation

POST /v1/auth/invitations/:token/accept

The user clicks the invitation link, which resolves the token and adds them as a member with the specified role.

List pending invitations

GET /v1/auth/organizations/:orgId/invitations

Revoke invitation

DELETE /v1/auth/organizations/:orgId/invitations/:invitationId

Organization-scoped roles

The organization plugin supports role-based access within organizations:

Roles are stored on the member record and can be customized per organization.

Multi-tenancy support

The organization plugin integrates with the engine's tenant isolation:

• Each organization has a unique ID used as the tenant identifier
• Sessions can be scoped to an organization context
• API operations filter by the current tenant
• Organization lifecycle hooks notify other plugins of tenant changes

GDPR data export

The plugin implements DataExportContributor to include organization memberships in user data exports:

func (p *Plugin) ExportUserData(ctx context.Context, userID id.UserID) (string, any, error) {
    orgs, err := p.store.ListUserOrganizations(ctx, userID)
    return "organizations", orgs, err
}

Lifecycle hooks

The organization plugin emits hooks that other plugins can subscribe to:

Observability

Events are emitted to Chronicle (audit log), Relay (webhooks), and the global hook bus for all organization and membership operations.