An Organization is a way to group Users within an Issuer. Organizations enable multi-tenancy, team management, and B2B features—they’re how you represent your customers’ companies, workspaces, or teams within your application.

If you’re building a B2B SaaS product, each of your customers is likely an Organization. Their employees are Users who belong to that Organization with specific roles and permissions.

When to Use Organizations

Organizations add structure when your users aren’t just individuals—they’re part of something larger.

Multi-Tenant SaaS

The most common use case. Each of your customers (companies) is an Organization:

• Acme Corp signs up for your project management tool
• You create an Organization for Acme Corp
• Acme’s employees join as members of that Organization
• Each member has roles like “Admin”, “Manager”, or “Viewer”
• Acme’s data is isolated from other customers’ Organizations

This model lets you:

• Bill per Organization (per-seat or per-organization pricing)
• Provide workspace isolation between customers
• Let customers manage their own team members
• Offer Organization-level settings and customization

Team Workspaces

Even within a single company, you might use Organizations to represent teams or departments:

• A large enterprise uses your analytics platform
• Each department (Sales, Engineering, Marketing) is an Organization
• Employees can belong to multiple Organizations
• Permissions are scoped per Organization

B2B Marketplaces

For platforms connecting businesses:

• Vendors and buyers are each Organizations
• Organization profiles include business details (company number, VAT, etc.)
• Trust is established at the Organization level, not individual user level

When NOT to Use Organizations

If your application is purely B2C with no team or company concept, you might not need Organizations at all. A social media app, personal finance tracker, or individual productivity tool typically doesn’t need to group users into Organizations.

You can always add Organizations later if your product evolves to include team features.

Organization Data

Basic Information

Every Organization has:

Name: The organization’s display name (e.g., “Acme Corporation”). This is what members see when they log in or switch between Organizations.

Description: Optional rich text describing the organization. Useful for internal directories or marketplace profiles.

Logo URL: A URL pointing to the organization’s logo. Display this in your UI to help users identify which Organization they’re working in.

Organization Type: One of business, nonprofit, or government. This affects which business detail fields are relevant and can be used for compliance or pricing purposes.

Business Details

Organizations can store detailed business information:

For businesses:

• Legal name and legal form (LLC, Corporation, etc.)
• Company registration number
• Tax ID and VAT number
• Registration date and jurisdiction
• Registered address
• Industry sector

For nonprofits:

• Charity registration number
• Sector (education, healthcare, etc.)

For government:

• Department name
• Jurisdiction

This data is useful for:

• B2B verification and trust
• Tax and billing compliance (especially for VAT in Europe)
• Regulatory requirements that need verified business information
• Marketplace profiles where buyers want to verify sellers

Contact Information

Organizations can have contact details:

• Primary email address
• Phone number
• Website URL
• Social media links (LinkedIn, Twitter, etc.)

These are useful for B2B communication, directory listings, and customer support.

Custom Fields and Metadata

Custom fields (visible): Store organization-specific data that doesn’t fit standard fields. Examples: subscription_tier, industry, account_manager.

Metadata (admin-only): Internal data never returned to users or client applications. Examples: salesforce_id, internal_notes, migration_batch.

Memberships

Users belong to Organizations through memberships. A membership represents the relationship between a specific user and a specific organization.

Membership Data

Each membership includes:

Status: Whether the membership is active or suspended. Suspended members can’t access organization resources but haven’t been fully removed.

Scopes: The permissions this user has within this organization. Scopes are strings like org:admin, org:member, projects:write, or billing:read.

Title: An optional role title like “Engineering Manager”, “Sales Rep”, or “Account Owner”. This is for display purposes—actual permissions come from scopes.

Metadata: Admin-only data specific to this membership.

Timestamps: When the user joined and when the membership was last updated.

User Scopes vs. Membership Scopes

Users have two levels of permissions:

User scopes: Global permissions that apply everywhere, regardless of organization context. These typically include OIDC scopes like openid, profile, and email.

Membership scopes: Organization-specific permissions that only apply when the user is acting within that organization.

For example, a user might have:

• User scopes: openid, profile, email
• Membership in Org A: org:admin, billing:write
• Membership in Org B: org:member, projects:read

When the user accesses Org A, they have admin and billing permissions. When they access Org B, they only have member-level access to projects.

Default Member Scopes

Organizations can configure default scopes that are automatically granted to new members. When someone joins (via invitation or direct add), they receive these default scopes.

When to use defaults: Set sensible defaults for typical members. If most people joining are regular team members, default to org:member. Admins can then upgrade specific users to additional scopes.

When to be explicit: For security-sensitive organizations, you might prefer no default scopes, requiring explicit permission grants for every member.

Multiple Organization Membership

Users can belong to multiple Organizations within the same Issuer. This is common for:

• Consultants who work with multiple client companies
• Employees at companies with multiple divisions
• Freelancers on a platform with multiple clients

Your application should provide UI for users to switch between Organizations or see which Organization context they’re currently in.

Invitations

Organizations can invite users via email. The invitation system handles the flow of bringing new people into an Organization.

Invitation Flow

1. Admin creates invitation: An organization admin sends an invitation to an email address, specifying the scopes and optional title the invitee will receive.

2. Email sent: The invitee receives an email with a secure link containing a challenge code.

3. Invitee accepts: The invitee clicks the link, authenticates (or creates an account if new), and accepts the invitation.

4. Membership created: Upon acceptance, a membership is automatically created with the specified scopes.

Invitation States

Invitations can be in several states:

Pending: The invitation has been sent but not yet accepted or declined. The invitee can still accept.

Accepted: The invitee accepted and is now a member of the organization.

Declined: The invitee explicitly declined the invitation.

Expired: The invitation’s expiration time passed without action. Default expiration is 7 days; maximum is 30 days.

Revoked: An admin cancelled the invitation before it was accepted or declined.

Invitation Settings

Organizations can configure how invitations work:

Invitations enabled: Whether the organization accepts new invitations at all. When disabled, creating an invitation is rejected. Disable this if you’re managing membership through other means (API provisioning, SSO).

Custom message: A personalized message included in invitation emails. Use this to explain what the organization is and why the person is being invited.

Invitation Security

Invitations use several security measures:

Challenge codes: Each invitation has a unique 45-character code that must be presented to accept or decline. This prevents unauthorized acceptance.

Expiration: Invitations automatically expire, preventing stale invitations from being accepted months later.

Single use: Once an invitation is accepted, declined, or revoked, the challenge code is invalidated.

Uniqueness: Only one pending invitation can exist per email address per organization. To re-invite someone, revoke the old invitation first.

Managing Invitations

Admins can:

• List invitations: See all pending, accepted, declined, expired, and revoked invitations.
• Resend invitations: Send a reminder email for pending invitations.
• Update invitations: Change the scopes or title before the invitation is accepted.
• Revoke invitations: Cancel a pending invitation.

Organization Settings

Member Limits

Organizations can have a maximum member count (max_members). This is useful for:

• Pricing tiers: Free tier limited to 5 members, Pro tier to 50, Enterprise unlimited.
• Resource management: Prevent organizations from growing beyond what your infrastructure supports.
• Compliance: Some regulations require limiting access to certain numbers of users.

When the limit is reached, new members cannot be added until existing members are removed or the limit is increased.

Default Scopes

Configure which scopes new members receive automatically. This reduces administrative overhead for common membership patterns.

Invitation Configuration

As described above, control whether invitations are enabled.

Organization Lifecycle

Creation

Organizations are created through the Core API. You can:

• Create an empty organization and add members later
• Create an organization with an initial member (typically the creator as admin)
• Set initial settings like name, type, and member limits

Auto-creation on signup: If your Issuer has “auto-create organization” enabled, a new Organization is automatically created when a user signs up. This is useful for B2B SaaS where every new signup represents a new customer company.

Status Management

Organizations have a status that controls whether they’re operational:

Active: Normal state. Members can access the organization, invitations work, and all features are available.

Suspended: The organization is temporarily disabled, but its data remains intact. Use suspension for:

• Non-payment (suspend until payment is resolved)
• Policy violations under investigation
• Temporary maintenance or migration

Suspension is enforced at token issuance: the suspended organization’s claims are excluded from newly issued tokens — fresh logins, token refreshes, and /userinfo responses. Access tokens issued before the suspension keep their organization claims until they expire, so propagation is bounded by your access token lifetime (30 minutes by default, configurable per client). Users are not logged out and their other organization memberships are unaffected — suspension removes the organization from their tokens, not the user from your application. Invitations cannot be accepted while the organization is suspended; they stay pending and become acceptable again after reactivation.

For immediate back-end revocation, subscribe to the organization.suspended webhook event and invalidate your own application sessions for that organization when it fires. organization.reactivated signals the reverse transition. Both fire in addition to organization.updated.

Deleted: The organization has been permanently removed along with all memberships, invitations, and API keys.

Deletion

Deleting an organization is permanent and cascades to:

• All API keys owned by the organization — revoked before anything else is removed, so a key can never outlive its org; each revocation emits api-key.deleted. If any revocation fails, the deletion aborts and can be retried.
• All memberships (users lose access but their accounts remain)
• All pending invitations
• Organization settings and metadata

Users who were members of a deleted organization aren’t deleted—they simply no longer have that membership.

When to delete vs. suspend: Suspend if the situation might be resolved (non-payment, policy review). Delete only when you’re certain the organization should be permanently removed and its data is no longer needed.

Organizations and Your Application

Displaying Organization Context

When users can belong to multiple Organizations, your application should clearly indicate which Organization they’re currently working in:

• Show the Organization name and logo in your navigation
• Provide an Organization switcher if users have multiple memberships
• Scope data and actions to the current Organization

Authorization Checks

When a user attempts an action, check both:

1. User authentication: Is the user logged in with a valid session?
2. Organization authorization: Does the user’s membership in this Organization include the required scopes?

For example, to delete a project:

// Pseudocode
if (user.isAuthenticated() &&
    user.getMembership(orgId).scopes.includes('projects:delete')) {
  deleteProject(projectId);
}

Organization-Scoped Data

Most data in a multi-tenant application should be scoped to an Organization:

• Projects belong to an Organization
• Files belong to an Organization
• Settings are per-Organization

When querying data, always filter by the current Organization to prevent data leakage between tenants.

Onboarding Flows

Consider how new users join Organizations:

Invitation-first: Users receive an invitation email, click the link, create an account (if new), and land in the Organization. Good for B2B where the Organization admin controls who joins.

Signup with auto-org: Users sign up, an Organization is auto-created for them, and they become its first admin. Good for self-service B2B SaaS where anyone can start a new workspace.

Domain-based: Users with certain email domains are automatically added to the corresponding Organization. Good for enterprise customers where you want @acme.com employees to automatically join Acme’s Organization.

Managing Organizations

API Operations

Organizations are managed through the Core API:

Operation	Endpoint
Create organization	POST /accounts/{account_id}/issuers/{issuer_id}/organizations
Get organization	GET .../organizations/{org_id}
List organizations	GET .../organizations
Update organization	PATCH .../organizations/{org_id}
Delete organization	DELETE .../organizations/{org_id}

Membership operations:

Operation	Endpoint
Add member	POST .../organizations/{org_id}/members
List members	GET .../organizations/{org_id}/members
Update member	PATCH .../organizations/{org_id}/members/{user_id}
Remove member	DELETE .../organizations/{org_id}/members/{user_id}

Invitation operations:

Operation	Endpoint
Create invitation	POST .../organizations/{org_id}/invitations
Get invitation	GET .../organizations/{org_id}/invitations/{invite_id}
List invitations	GET .../organizations/{org_id}/invitations
Update invitation	PATCH .../organizations/{org_id}/invitations/{invite_id}
Revoke invitation	DELETE .../organizations/{org_id}/invitations/{invite_id}
Accept invitation	POST .../organizations/{org_id}/invitations/{invite_id}/accept
Decline invitation	POST .../organizations/{org_id}/invitations/{invite_id}/decline
Resend invitation	POST .../organizations/{org_id}/invitations/{invite_id}/resend

Filtering and Pagination

When listing organizations or members, results are paginated. Use limit and offset parameters for large datasets.

Invitations can be filtered by status (pending, accepted, declined, expired, revoked).

Example Scenarios

Project Management SaaS

Structure:

• Each customer company is an Organization
• Company employees are members with roles: Owner, Admin, Member, Guest
• Projects and tasks are scoped to Organizations

Membership scopes:

• org:owner - Full control including billing and deletion
• org:admin - Manage members and settings
• org:member - Create and edit projects
• org:guest - View-only access

Invitation flow:

• Admins invite team members by email
• Invitees receive branded email with company name
• On acceptance, they get org:member scope by default
• Admins can upgrade to org:admin as needed

Settings:

• Free tier: max_members: 5
• Pro tier: max_members: 50
• Enterprise: max_members: null (unlimited)

Marketplace Platform

Structure:

• Vendors and buyers are both Organizations
• Organization type distinguishes them: business for vendors, could use custom fields for buyer vs. seller
• Business details (tax ID, VAT) required for vendors

Organization data:

• Vendors have complete business_details for verification
• Vendor logos displayed in marketplace listings
• Contact information for customer support

Trust model:

• Transactions are between Organizations, not individual users
• Verification happens at Organization level
• Multiple employees can act on behalf of their Organization

Enterprise with Departments

Structure:

• Single enterprise customer with one Issuer
• Each department (Engineering, Sales, Marketing) is an Organization
• Employees can belong to multiple Organizations

Cross-org access:

• Some users are in multiple Organizations (e.g., managers overseeing multiple departments)
• Organization switcher in UI lets users change context
• Reports can aggregate across Organizations for executives

Scopes:

• Department-specific: engineering:deploy, sales:quotes, marketing:campaigns
• Shared: org:member, reports:read

Consulting Firm

Structure:

• The consulting firm has one Issuer
• Each client engagement is an Organization
• Consultants are members of multiple client Organizations

Membership management:

• When a project ends, consultant is removed from that Organization
• When a new project starts, consultant is added to the new Organization
• Consultants see only the clients they’re currently assigned to

Time tracking:

• Custom fields on membership: hourly_rate, budget_remaining
• Metadata: engagement_start_date, project_manager

Security Considerations

Data Isolation

Organizations provide logical isolation, but your application must enforce it:

• Always filter data queries by Organization ID
• Verify Organization membership before granting access
• Don’t leak information about other Organizations (member counts, names, etc.)

Scope Management

• Grant minimum necessary scopes to members
• Review and audit high-privilege scopes (org:admin, billing:write)
• Consider time-limited elevated access for sensitive operations

Invitation Security

• Invitations expire automatically—don’t extend expiration indefinitely
• Monitor for invitation abuse (mass invitations to random emails)
• Disable invitations entirely (invitation_enabled: false) for organizations whose membership is managed by provisioning

Audit Trail

AuthPI emits events for all Organization operations:

• organization.created, organization.updated, organization.deleted
• organization.suspended, organization.reactivated (status transitions, emitted alongside organization.updated)
• organization.membership.created, organization.membership.updated, organization.membership.deleted
• organization.invitation.created, organization.invitation.accepted, organization.invitation.declined, organization.invitation.deleted

Use these events to maintain audit logs for compliance and security review.

Next Steps

• Learn about Users who become Organization members
• Understand Issuers that contain Organizations
• See how Clients access Organization-scoped resources
• Monitor Organization activity with Events