Identity, access, ownership, and payment context for connected applications.
Kimezu is a central identity, ownership, access, and payment context layer for multi-application ecosystems. It provides a single source of truth for users, groups, permissions, sessions, and payment profiles across connected applications.
Operator model. Kimezu is the white-label distribution of the identity protocol for multi-tenant ecosystems. This reference documents integration concepts; the marketing docs hub covers product setup and API surfaces.
Kimezu is the white-label, operator-ready distribution of Kimezu for multi-tenant ecosystems. Instead of shipping one-off installations, Kimezu gives tenants their own “app as a product” experience while keeping the core Kimezu security, authorization, and session model centralized.
Tenants get isolated namespaces, branded configuration, and tenant-scoped settings (including payments and access control). Consuming applications still receive the same verified actor information and context model, so your integration code stays consistent across tenants.
This documentation focuses on Kimezu’s integration model. As Kimezu features mature, this section will expand with concrete tenant setup and migration guidance—without changing the Kimezu contract your applications rely on.
Most authentication systems are designed for single applications. Real systems aren't. Users move between apps. Groups own resources. Permissions need to stay consistent. Sessions shouldn't break at every boundary. Kimezu exists to solve this at the core, by acting as a shared identity and ownership layer, not just a login service.
Kimezu is designed for organizations building multiple connected applications that need shared identity across applications, consistent authorization decisions, centralized ownership and payment context, and cross-application session management.
This documentation is for developers integrating with Kimezu, contributors, and technical readers who want to understand the architecture and model. Kimezu is currently for internal use; this documentation describes the architecture and integration model and does not share sensitive data, database schemas, or internal implementation details.
Kimezu provides:
Kimezu does not provide application business logic, user interfaces, payment processing or execution, application-specific data storage, or stable external API contracts.
A user is a single identity that exists across all connected applications. Each user has a unique identifier, authentication credentials, profile information, and membership in zero or more groups. Users can own resources and have permissions granted directly or through group membership.
Groups represent collections of users with shared ownership, permissions, or context. Groups can own resources, receive payments, and have permissions that apply to all members. Groups are scoped to specific applications but can be referenced across the ecosystem.
Roles are named collections of permissions. Roles can be assigned to users or groups within an application context. A role defines what actions are allowed, not who can perform them. Role assignments determine effective permissions.
Permissions are fine-grained access controls that define what actions can be performed on what resources. Permissions are evaluated centrally by Kimezu but enforced by consuming applications. Permissions can be granted directly to users or inherited through group membership and roles.
An application is a connected system that consumes Kimezu's identity, authorization, and context services. Each application has its own namespace for groups, roles, and permissions, while sharing the same user identity space. Applications are responsible for enforcing authorization decisions made by Kimezu.
A session represents an authenticated user's active state across the ecosystem. Sessions are managed centrally by Kimezu and can be shared across multiple applications. Sessions carry identity, permissions, and context information that applications use to make authorization decisions.
Ownership determines who has control over resources and actions. Resources can be owned by users or groups. Ownership affects authorization decisions—owners typically have elevated permissions on their resources. Ownership is tracked as part of the context that Kimezu provides to applications.
Context is the complete set of information about a user's current state: identity, group memberships, permissions, ownership relationships, and application-specific data. Context is assembled by Kimezu and provided to applications to enable consistent authorization decisions across the ecosystem.
Kimezu supports three actor types: User, Group, and Agent. Agents are AI-driven actors that operate on behalf of a user or group within a specific application context.
An Agent is a non-human identity that can authenticate to connected applications via Kimezu. It has its own scoped permissions, a revocable API token, and a clear owner (a user or group). Agents cannot log in through a UI — they authenticate exclusively via API token.
When an agent authenticates, the session JWT includes extra claims that consuming applications can inspect:
{
"actor_type": "agent",
"actor_id": "<agent-uuid>",
"sub": "<owner-user-id>",
"aud": "<application-id>"
}
Consuming applications should check actor_type and handle agent sessions differently where needed — for example, disabling UI-only flows or applying stricter rate limits.
An agent can only be granted permissions that its owner already holds. Permission escalation is not possible — the system enforces this at grant time. An agent's effective access is always a subset of its owner's access.
Agents are managed via the Kimezu dashboard (Agents section) or the API. Tokens are shown once at creation and cannot be recovered — only revoked. When an agent is revoked, its token immediately stops working across all connected applications.
Kimezu maintains a single identity for each user across all connected applications. When a user authenticates, they authenticate once to Kimezu, not to individual applications. This identity is consistent and persistent across the entire ecosystem.
Authentication happens at the Kimezu layer. Applications do not maintain separate authentication systems. When a user logs in, Kimezu establishes a session that can be used by any connected application. Applications receive identity information from Kimezu, not from their own authentication mechanisms.
Users are created in Kimezu's central identity store. Once created, a user exists across all applications. User profiles can include application-specific metadata, but core identity attributes are shared. Users can be deactivated, which affects their access across all applications, or deleted, which removes them from the system entirely.
Groups are created within application contexts but can be referenced ecosystem-wide. A user can be a member of multiple groups, potentially across different applications. Group membership affects permissions and ownership context. Groups can have owners, who are typically users with administrative privileges over the group.
Kimezu uses a permission-based authorization model. Permissions are granular statements about what actions can be performed on what resources. Permissions are evaluated centrally by Kimezu, but enforcement happens in consuming applications.
Roles provide a way to bundle permissions together. A role can be assigned to a user or group within an application context. When assigned to a group, all members of that group inherit the role's permissions. Permissions can also be granted directly to users or groups without using roles.
Kimezu makes authorization decisions centrally. When an application needs to know if a user can perform an action, it queries Kimezu with the user's identity, the requested action, and the resource context. Kimezu evaluates all relevant permissions—direct grants, role-based permissions, and group memberships—and returns an authorization decision.
Centralizing permissions ensures consistency across applications. If a user's permissions change, that change is reflected immediately across all applications. There is no need for synchronization jobs or eventual consistency mechanisms. Applications always receive the current, authoritative permission state.
An application integrates with Kimezu by delegating identity, authorization, and context management to Kimezu. The application does not maintain its own user database, authentication system, or permission store. Instead, it queries Kimezu for identity information and authorization decisions.
Applications are responsible for:
Applications are not responsible for authenticating users, making authorization decisions, managing user credentials, or maintaining permission state.
Applications receive from Kimezu:
Applications must handle storing application-specific data, implementing business logic, rendering user interfaces, processing payments (Kimezu provides payment profiles, not payment execution), and application-specific workflows and state management.
Resources can be owned by either users or groups. User ownership is straightforward—a single user has control. Group ownership means the group collectively owns the resource, and group members may have permissions based on their membership. Ownership affects authorization decisions and payment routing.
Ownership is tracked as part of the context that Kimezu maintains. When an application queries for authorization, it provides resource context, including ownership information. Kimezu evaluates permissions in the context of ownership—owners typically have elevated permissions, and group members may have permissions based on group ownership.
Ownership is a factor in authorization decisions. A user who owns a resource may have different permissions than a user who does not. Group ownership means all group members may have permissions based on the group's ownership. Ownership relationships are part of the context that applications provide when querying for authorization.
In multi-application systems, context is essential for consistent authorization. A user's permissions may vary depending on which application they're using, which group they're acting on behalf of, or which resource they're accessing. Kimezu assembles this context and uses it to make consistent authorization decisions across all applications.
Payments are a form of ownership and context. Users and groups need payment profiles to receive payments, and applications need to know which payment profile to use in different contexts. By managing payment profiles centrally, Kimezu ensures consistent payment routing across applications and maintains the relationship between identity and payment capability.
Payment profiles are attached to users or groups. A user can have a personal payment profile, and a group can have a group payment profile. Payment profiles contain information about payment methods (Stripe accounts, PayPal emails, Mollie customer IDs) but do not contain payment processing logic.
Applications can query Kimezu for payment profiles in specific contexts. For example, if a group owns a resource and receives payment for that resource, the application can query Kimezu for the group's payment profile. Kimezu returns the appropriate profile based on ownership and context.
Kimezu supports payment processing through Stripe (cards), PayPal, and Mollie (iDEAL, SEPA Direct Debit, Bancontact). Payment provider selection is handled automatically based on user preferences, app configuration, and country defaults. Kimezu manages the full payment lifecycle including checkout, webhooks, and refunds.
Kimezu explicitly does not process payments. It manages payment profiles—information about where payments should be sent—but does not execute payment transactions, handle payment flows, or interact with payment processors beyond storing account information. Applications are responsible for using payment profiles to execute actual payment transactions.
Kimezu is responsible for storing payment profile information, associating payment profiles with users and groups, and providing payment profiles to applications in context.
Kimezu is not responsible for executing payment transactions, handling payment flows or user interactions, interacting with payment processors beyond account storage, managing payment disputes or refunds, or processing payment webhooks or callbacks.
This section explains how Kimezu handles value-added tax (VAT) and taxes for payments, in plain language for end users and sellers. It does not cover technical implementation or specific rates.
When you sell digital services or goods to customers in the European Union (EU), VAT often applies. Who pays it, how much, and how it is reported depends on where your customer is based and whether they are a business or a consumer. Kimezu helps you stay consistent and transparent by applying clear rules at the time of each payment and keeping a record of how VAT was treated.
At the time of payment
After the payment
VAT
A tax on goods and services in the EU. Rates and rules differ by country. Kimezu uses the applicable rules at the time of payment; we do not publish or guarantee specific rates here.
Reverse charge
For qualifying business-to-business (B2B) sales within the EU, VAT is not added to the price. Instead, the buyer’s country treats the supply as subject to VAT there. Kimezu records when reverse charge was applied so your invoices and records are correct.
Outside EU scope
Sales to customers outside the EU are generally not subject to EU VAT. Kimezu records these as “outside EU scope” so it is clear that no EU VAT was charged.
Your billing country
The country you use for billing (e.g. where your business is established) can matter for which rules apply. Kimezu uses the billing information provided at payment time to apply the right treatment.
If you sell digital services to consumers in multiple EU countries, you may have to report and pay VAT in each country where your customers are located. Many businesses use the EU One-Stop Shop (OSS) scheme to report and pay in one place instead of registering in every country.
If a payment is refunded, the VAT treatment follows the original transaction. The refund is recorded in a way that is consistent with the original sale (e.g. same VAT treatment and clear linkage to the original payment). This helps keep your books and any reporting aligned.
For technical or integration details, see the rest of the Kimezu documentation. For specific rates or legal advice, consult your tax authority or advisor.
Kimezu manages sessions centrally. When a user authenticates, Kimezu creates a session that represents their authenticated state. This session is valid across all connected applications and contains identity, permission, and context information.
Sessions are shared across applications. When a user logs into one application, they are effectively logged into all applications that trust Kimezu's session state. Applications can query Kimezu to validate sessions and retrieve current user context without requiring separate authentication.
Kimezu uses tokens to represent sessions and carry identity information. These tokens are issued by Kimezu and validated by applications. Tokens contain identity and permission information that applications use to make authorization decisions. Token formats and validation mechanisms are internal implementation details.
Sessions are created on authentication and can be invalidated explicitly (logout) or automatically (expiration, security events). When a session is invalidated, it becomes invalid across all applications immediately. Applications are responsible for respecting session validity and re-authenticating when sessions expire.
Kimezu implements secure authentication practices including strong password hashing, secure session management, and protection against common authentication attacks. Authentication credentials are stored securely and never exposed to applications. Applications receive only identity information, not credentials.
Authorization decisions are made centrally by Kimezu, but enforcement happens in applications. Kimezu provides clear authorization decisions, and applications are responsible for respecting these decisions. This separation ensures that authorization logic is centralized while allowing applications to implement enforcement in ways that fit their architecture.
Kimezu implements rate limiting and abuse prevention mechanisms to protect against brute force attacks, credential stuffing, and other abuse patterns. These mechanisms operate at the authentication and API layers to prevent abuse before it reaches applications.
Kimezu maintains audit logs of authentication events, authorization decisions, and administrative actions. These logs provide a record of who did what and when, enabling security investigations and compliance requirements. Applications can also maintain their own audit logs for application-specific events.
Kimezu is designed to scale with the number of connected applications and users. The architecture assumes that adding new applications does not require changes to existing applications or to Kimezu's core systems. Each application integration is independent.
Applications integrate with Kimezu in a stateless manner. Applications do not maintain persistent connections or server-side state with Kimezu. Instead, they make stateless requests for identity and authorization information as needed. This allows applications to scale independently and simplifies deployment.
Kimezu is designed to scale horizontally. The system can handle increased load by adding more instances rather than requiring more powerful hardware. This design assumes that session state and authorization decisions can be made without requiring coordination between instances for most operations.
Kimezu assumes that applications can make network requests to Kimezu, network latency between applications and Kimezu is acceptable for authorization queries, applications handle Kimezu unavailability gracefully, and applications implement appropriate caching of authorization decisions when needed.
Kimezu is designed with modularity in mind. New capabilities can be added without disrupting existing functionality. The permission model, ownership model, and payment profile system are all designed to evolve over time without breaking existing integrations.
New applications can be added to the ecosystem without affecting existing applications. Each application has its own namespace for groups, roles, and permissions, so adding a new application does not create conflicts with existing applications. User identity is shared, but application-specific data is isolated.
The permission model, ownership model, and other core concepts can evolve over time. Kimezu is designed to support new permission types, new ownership patterns, and new context information without requiring changes to all consuming applications. Applications can adopt new capabilities as needed.
Kimezu does not provide business logic or application workflows, user interfaces or frontend components, payment processing or execution, application-specific data storage, content management or media handling, communication or messaging systems, analytics or reporting beyond audit logs, or stable external API contracts for third-party integration.
Kimezu excludes payment execution (Kimezu manages payment profiles but does not process payments), UI components (applications must build their own user interfaces), business logic (applications implement their own workflows and rules), data storage (applications store their own application-specific data), and external APIs (Kimezu does not provide stable external API contracts).
Do not use Kimezu for storing application-specific business data, implementing application workflows, processing payments directly, building user-facing features that should be in applications, creating dependencies on internal implementation details, or assuming API stability or external support guarantees.
Application: A connected system that consumes Kimezu's identity, authorization, and context services. Each application has its own namespace for groups, roles, and permissions.
Authorization: The process of determining whether a user has permission to perform an action. Kimezu makes authorization decisions centrally.
Context: The complete set of information about a user's current state, including identity, group memberships, permissions, and ownership relationships.
Group: A collection of users with shared ownership, permissions, or context. Groups can own resources and have permissions that apply to all members.
Identity: A user's unique identifier and profile information that exists across all connected applications.
Ownership: The relationship between a user or group and a resource. Ownership affects authorization decisions.
Payment Profile: Information about payment methods (Stripe accounts, PayPal emails, etc.) attached to users or groups. Kimezu manages payment profiles but does not process payments.
Permission: A fine-grained access control that defines what actions can be performed on what resources. Permissions are evaluated centrally by Kimezu.
Role: A named collection of permissions that can be assigned to users or groups within an application context.
Session: An authenticated user's active state across the ecosystem. Sessions are managed centrally by Kimezu and shared across applications.
User: A single identity that exists across all connected applications, with authentication credentials, profile information, and group memberships.