Identity Base 0.6.3: Comprehensive Documentation Overhaul
Published: November 9, 2025
Identity Base 0.6.3 introduces self-service organization management, header-based context switching, and unified pagination across all APIs. These are significant architectural changes that affect how you integrate the package into your applications. To support these changes, we've completely overhauled the documentation.
This isn't just release notes and API references. We've added three distinct types of documentation that address different integration needs: end-to-end guides that walk through complete implementations, step-by-step playbooks for specific tasks, and detailed package references that explain configuration and behavior.
The Documentation Gap We're Filling
When you're integrating an identity management package, you typically need answers to three different types of questions. "How do I build a complete onboarding flow?" requires understanding the entire system and how pieces fit together. "How do I implement invitation acceptance?" needs a focused, sequential walkthrough of one specific task. "What configuration options does the Organizations package expose?" demands reference documentation you can scan quickly.
Previous Identity Base documentation mixed these concerns. Architectural explanations sat alongside configuration examples. Code snippets appeared without context about which integration scenario they belonged to. If you wanted to understand the full picture of how organization permissions worked, you had to piece it together from multiple README files and code comments.
The 0.6.3 documentation separates these concerns clearly. Guides provide the big picture - how systems work together, what architectural decisions you need to make, and how to think about integration patterns. Playbooks give you concrete, testable sequences for specific operations - accept an invitation, seed default roles, migrate databases. Package references document every configuration option, environment variable, and middleware registration pattern for each NuGet package.
Guides: Understanding the System
The guides section contains end-to-end explanations of major Identity Base concepts and integration patterns. These are the documents you read when you're trying to understand how something works architecturally or planning your integration approach.
Organization Onboarding Flow walks through building a complete user onboarding experience that includes organization creation, team invitations, and role assignments. It covers both the happy path and edge cases like invitation expiry, duplicate invitations, and role conflicts. You'll see how the self-service APIs compose with your application's onboarding UI and where to implement validation logic.
Organization Admin Use Case explores administrative operations for managing organizations across your platform. This is relevant if you're building customer support tools, billing admin panels, or system monitoring dashboards that need to work across all organizations rather than within a single organizational context.
Full-Stack Integration Guide demonstrates integrating Identity Base into a complete application stack - backend API, web frontend, database, and deployment pipeline. It shows where authentication middleware fits in your ASP.NET Core pipeline, how to structure React components that consume identity APIs, and how to handle token refresh in single-page applications.
Identity Permissions Claim explains how permissions work in Identity Base - how claims are structured in JWTs, how organization membership affects permission resolution, when permissions are evaluated versus when they're issued, and how the header-based context model changes permission merging behavior.
Additional guides cover Docker deployment, admin operations, and database management patterns. Each guide assumes you understand basic authentication concepts but provides context about Identity Base's specific architecture and decisions.
Where to find guides:
https://github.com/Amaretto-Software-Labs/identity-base/tree/main/docs/guides
Playbooks: Step-by-Step Procedures
Playbooks are focused, sequential instructions for accomplishing specific tasks. These are the documents you follow when you know what you want to do but need the exact sequence of API calls, database operations, or configuration changes.
Organization Invitation Flow provides the complete sequence for implementing team invitations - creating the invitation record, generating the invitation link, sending the email, handling the acceptance flow, and dealing with errors like expired invitations or invalid tokens. The playbook includes example code for both the backend API calls and frontend UI state management.
Seed Roles and Default Organization walks through configuring initial roles and permissions for your application. This covers the Organizations:RoleOptions:Seeds configuration, assigning permissions to roles, creating a default organization for testing, and verifying the seed data was created correctly. You'll use this during initial setup and when adding new organizational capabilities to your application.
Database Migrations and Rollback covers running EF Core migrations for Identity Base, understanding what each migration changes, rolling back migrations when needed, and handling migration conflicts in team environments. This is essential reading before deploying version upgrades that include schema changes.
Admin API Smoke Test gives you a sequence of API calls you can run to verify your admin endpoints are configured correctly - creating test organizations, assigning roles, checking permission resolution, and cleaning up test data. This is useful after initial deployment or when troubleshooting permission issues.
React Client PKCE Login demonstrates implementing OAuth's PKCE (Proof Key for Code Exchange) flow in a React single-page application. This playbook includes the authorization request, code exchange, token storage, and refresh logic with specific attention to security considerations like state validation and token storage.
Additional playbooks cover common operational tasks and integration patterns. Each playbook is designed to be followed sequentially - if you execute the steps in order, you'll accomplish the task and have a verifiable result.
Where to find playbooks:
https://github.com/Amaretto-Software-Labs/identity-base/tree/main/docs/playbooks
Package References: Configuration and API Details
Package-level documentation provides detailed reference material for each NuGet package in the Identity Base ecosystem. These documents catalog configuration options, middleware registration patterns, dependency injection setup, and available endpoints.
Identity.Base covers core authentication functionality - JWT configuration, token lifetime settings, claim customization, and authentication middleware registration. You'll reference this when configuring token issuance, customizing claims, or troubleshooting authentication failures.
Identity.Base.Roles documents role-based access control features - role creation, permission assignment, role hierarchy, and permission checking patterns. This package reference explains how to seed roles, query role assignments, and implement custom authorization policies based on roles.
Identity.Base.Admin details the admin API surface - endpoints for managing users, organizations, and system configuration, along with the scope requirements and permission checks for each endpoint. You'll use this when building administrative tools or customer support interfaces.
Identity.Base.Organizations covers organization management features including the new self-service endpoints - organization creation, membership management, invitation flows, and role assignment within organizations. This reference explains all configuration options for organization behavior, including role seeds, invitation expiry, and context header configuration.
Companion packages (Claims, Permissions, etc.) each have their own reference documentation following the same structure. Every configuration option includes its type, default value, validation rules, and examples of common values.
Where to find package references:
https://github.com/Amaretto-Software-Labs/identity-base/tree/main/docs/packages
Recommended Integration Path for New Projects
If you're integrating Identity Base into a new application, follow this sequence:
Start with the Getting Started guide, which covers installation, initial configuration, and running your first authenticated request. This establishes the baseline - a working authentication system with token issuance.
https://github.com/Amaretto-Software-Labs/identity-base/blob/main/docs/guides/getting-started.md
Next, implement the Organization Onboarding Flow. This guide shows how to build a complete user registration and team setup experience using the self-service APIs. You'll implement organization creation during signup, team invitation after onboarding, and role assignment for different user types.
Then add header-based organization context to your application. The Identity Permissions Claim guide explains how context affects permission resolution, while the Full-Stack Integration Guide shows where to set the X-Organization-Id header in your client application and how to handle context switching in your UI.
Finally, wire up admin dashboards using the unified pagination contracts. The Admin Operations Guide demonstrates querying organizations, users, and memberships with pagination, search, and sorting. The Admin API Smoke Test playbook helps verify everything works correctly.
This sequence builds functionality incrementally - authentication first, then organizations, then context-aware permissions, then administration tools. Each step produces a working system that you can test before moving to the next integration.
Upgrading from 0.4.x or Earlier
If you're running an earlier version of Identity Base, the 0.6.3 release includes breaking changes that require migration. The documentation includes specific guidance for upgrading existing integrations.
Review the CHANGELOG first to understand what changed at the API level. The changelog documents every breaking change, deprecated feature, and new capability with version numbers and migration notes.
https://github.com/Amaretto-Software-Labs/identity-base/blob/main/CHANGELOG.md
Replace IsPrimary logic with the new header-based context model. Version 0.4.x and earlier used an IsPrimary flag to mark an "active" organization for each user. This flag is removed in 0.6.3. The Header-Based Organization Context guide explains the new model and provides migration patterns for updating your client code.
Refresh tokens when membership changes. The new permission model merges organization-scoped permissions only when the X-Organization-Id header is present. If your application relied on automatic permission updates when users joined organizations, you'll need to trigger token refresh to update claims, or switch to fetching permissions via the /users/me/permissions endpoint with appropriate headers.
Align role seeds with the new permission namespace. The 0.6.3 permission model uses user.organizations.* for self-service operations and admin.organizations.* for platform operations. If your role seeds assigned permissions like organizations.* globally, you'll need to update them to the new namespaces and adjust admin scopes accordingly.
The Database Migrations playbook covers running the schema migrations required for 0.6.3, including how to roll back if you encounter issues during upgrade.
Finding What You Need
The documentation repository organizes content by type, not by feature. This means guides, playbooks, and package references each have their own directories. When you need documentation:
- Understanding how something works architecturally? Check guides.
- Implementing a specific task step-by-step? Check playbooks.
- Looking up configuration options or API details? Check package references.
- Troubleshooting an error or unexpected behavior? Start with guides for context, then check playbooks for the relevant operation.
Each document cross-references related documentation. The Organization Onboarding Flow guide links to the Organization Invitation Flow playbook, which links to the Identity.Base.Organizations package reference, creating clear paths through the documentation based on what you're trying to accomplish.
Contributing to Documentation
The documentation lives in the Identity Base repository alongside the code. If you find gaps, unclear explanations, or missing examples, open an issue describing what documentation would have helped. We're prioritizing documentation work based on real integration needs and questions from the community.
If you've integrated a particular pattern and want to contribute a playbook or guide, pull requests are welcome. Follow the existing structure - guides explain architecture and integration patterns, playbooks provide sequential procedures, and package references document configuration comprehensively.
Useful Links
Main Documentation Hub:
https://github.com/Amaretto-Software-Labs/identity-base/tree/main/docs
Issues and Roadmap:
https://github.com/Amaretto-Software-Labs/identity-base/issues
Discussions and Q&A:
https://github.com/Amaretto-Software-Labs/identity-base/discussions
Sample Applications:
https://github.com/Amaretto-Software-Labs/identity-base/tree/main/apps
The sample applications demonstrate complete integration patterns for React-based organization flows, including organization creation, invitation handling, and role management. These are working examples you can run locally or reference when building your own integration.
Have feedback on the documentation or suggestions for topics we should cover? Open a discussion in the Identity Base repository - we're actively expanding documentation based on community needs.
