Simezu Documentation

1. Overview

Simezu 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.

SIMEZU and KIMEZU. SIMEZU is the pilot project for KIMEZU. That is why this documentation is still incomplete and will evolve. On KIMEZU, users will be able to use KIMEZU as their own auth and payment application—white-label identity and payments for their ecosystems.

Kimezu (white-label for multi-tenant ecosystems)

Kimezu is the white-label, operator-ready distribution of Simezu for multi-tenant ecosystems. Instead of shipping one-off installations, Kimezu gives tenants their own “app as a product” experience while keeping the core Simezu 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 Simezu’s integration model. As Kimezu features mature, this section will expand with concrete tenant setup and migration guidance—without changing the Simezu contract your applications rely on.

What Problems Simezu Solves

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. Simezu exists to solve this at the core, by acting as a shared identity and ownership layer, not just a login service.

Intended Usage and Audience

Simezu 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 Simezu, contributors, and technical readers who want to understand the architecture and model. SIMEZU 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.

System Boundaries

Simezu provides:

• Identity management and authentication
• Authorization decisions and permission enforcement
• Session management across applications
• Payment profile management (not payment processing)
• Ownership and context tracking

Simezu does not provide application business logic, user interfaces, payment processing or execution, application-specific data storage, or stable external API contracts.

2. Core Concepts

Users

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

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

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

Permissions are fine-grained access controls that define what actions can be performed on what resources. Permissions are evaluated centrally by Simezu but enforced by consuming applications. Permissions can be granted directly to users or inherited through group membership and roles.

Applications

An application is a connected system that consumes Simezu'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 Simezu.

Sessions

A session represents an authenticated user's active state across the ecosystem. Sessions are managed centrally by Simezu and can be shared across multiple applications. Sessions carry identity, permissions, and context information that applications use to make authorization decisions.

Ownership

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 Simezu provides to applications.

Context

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 Simezu and provided to applications to enable consistent authorization decisions across the ecosystem.

2b. Agent Identity

Simezu 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.

What is an Agent?

An Agent is a non-human identity that can authenticate to connected applications via Simezu. 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.

Actor Type in Session Context

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.

Principle of Least Privilege

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.

Managing Agents

Agents are managed via the Simezu 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.

3. Identity Model

Single Identity Across Applications

Simezu maintains a single identity for each user across all connected applications. When a user authenticates, they authenticate once to Simezu, not to individual applications. This identity is consistent and persistent across the entire ecosystem.

Centralized Login State

Authentication happens at the Simezu layer. Applications do not maintain separate authentication systems. When a user logs in, Simezu establishes a session that can be used by any connected application. Applications receive identity information from Simezu, not from their own authentication mechanisms.

User Lifecycle

Users are created in Simezu'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.

Group Membership and Scope

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.

4. Authorization Model

Permission-Based Access Control

Simezu uses a permission-based authorization model. Permissions are granular statements about what actions can be performed on what resources. Permissions are evaluated centrally by Simezu, but enforcement happens in consuming applications.

Roles and Group-Scoped Permissions

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.

Centralized Decision-Making

Simezu makes authorization decisions centrally. When an application needs to know if a user can perform an action, it queries Simezu with the user's identity, the requested action, and the resource context. Simezu evaluates all relevant permissions—direct grants, role-based permissions, and group memberships—and returns an authorization decision.

Why Permissions Live Centrally

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.

5. Application Integration

What Integration Means

An application integrates with Simezu by delegating identity, authorization, and context management to Simezu. The application does not maintain its own user database, authentication system, or permission store. Instead, it queries Simezu for identity information and authorization decisions.

Responsibilities of Consuming Applications

Applications are responsible for:

• Enforcing authorization decisions made by Simezu
• Storing and managing application-specific data
• Implementing business logic
• Providing user interfaces
• Handling application-specific workflows

Applications are not responsible for authenticating users, making authorization decisions, managing user credentials, or maintaining permission state.

What Applications Receive

Applications receive from Simezu:

• User identity and profile information
• Current group memberships
• Effective permissions for the current context
• Ownership relationships
• Session state and validity

What Applications Must Handle

Applications must handle storing application-specific data, implementing business logic, rendering user interfaces, processing payments (Simezu provides payment profiles, not payment execution), and application-specific workflows and state management.

6. Ownership & Context

Users vs Groups as Owners

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 of Resources and Actions

Ownership is tracked as part of the context that Simezu maintains. When an application queries for authorization, it provides resource context, including ownership information. Simezu evaluates permissions in the context of ownership—owners typically have elevated permissions, and group members may have permissions based on group ownership.

How Ownership Affects Authorization

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.

Why Context is Critical

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. Simezu assembles this context and uses it to make consistent authorization decisions across all applications.

7. Payments (High-Level)

Why Payments are Part of Simezu's Model

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, Simezu ensures consistent payment routing across applications and maintains the relationship between identity and payment capability.

Payment Profiles

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.

Per-Application Payment Context

Applications can query Simezu for payment profiles in specific contexts. For example, if a group owns a resource and receives payment for that resource, the application can query Simezu for the group's payment profile. Simezu returns the appropriate profile based on ownership and context.

Supported Providers

Simezu 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. Simezu manages the full payment lifecycle including checkout, webhooks, and refunds.

Simezu Does Not Process Payments

Simezu 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.

Boundaries of Responsibility

Simezu is responsible for storing payment profile information, associating payment profiles with users and groups, and providing payment profiles to applications in context.

Simezu 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.

8. VAT & Taxes

This section explains how SIMEZU 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.

Why VAT matters for your payments

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. SIMEZU 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.

What SIMEZU does for you

At the time of payment

• SIMEZU determines whether VAT applies to the transaction based on the buyer’s country and whether they are a business or a consumer.
• For EU consumers, VAT is typically added to the price and collected; the amount you receive reflects this.
• For EU businesses that provide a valid VAT number, the transaction may be treated as reverse charge: VAT is not added to the price, and the business customer accounts for VAT in their own country. SIMEZU records that this rule was applied.
• For customers outside the EU, VAT usually does not apply to the transaction (outside EU scope). SIMEZU records this so it is clear no EU VAT was charged.

After the payment

• Each payment keeps a clear record of how VAT was handled (e.g. VAT applied, reverse charge, or outside EU scope). This supports accurate invoicing and reporting.
• Invoices generated from SIMEZU reflect the VAT treatment that was applied at the time of the transaction, so sellers and buyers see a consistent story.

Key concepts (no jargon)

VAT

A tax on goods and services in the EU. Rates and rules differ by country. SIMEZU 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. SIMEZU 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. SIMEZU 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. SIMEZU uses the billing information provided at payment time to apply the right treatment.

Invoices and records

• Invoices generated through SIMEZU show the VAT treatment that was applied to the underlying payment (e.g. VAT included, reverse charge, or outside EU scope).
• When reverse charge applies, the invoice will indicate that clearly so both you and your customer have a correct record.
• All of this is derived from the VAT treatment recorded at the time of the transaction, so your records stay consistent and auditable.

EU reporting (OSS), high level

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.

• SIMEZU can provide previews and summaries of transaction data (e.g. by country and period) that may help you prepare your OSS or other VAT reporting.
• Submitting OSS returns and paying VAT to tax authorities remains your responsibility. SIMEZU does not submit returns or pay tax on your behalf; we help you see what happened in your transactions so you can report correctly.

Refunds

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.

Summary

• SIMEZU applies clear, consistent VAT rules at payment time and keeps a record of that treatment.
• You get transparency on whether VAT was applied, reverse charge was used, or the sale was outside EU scope.
• Invoices and internal summaries are based on this recorded treatment.
• OSS or other tax reporting and submission remain your responsibility; SIMEZU supports you with visibility and consistency, not with filing or paying tax for you.

For technical or integration details, see the rest of the SIMEZU documentation. For specific rates or legal advice, consult your tax authority or advisor.

9. Sessions & State

Central Session Handling

Simezu manages sessions centrally. When a user authenticates, Simezu creates a session that represents their authenticated state. This session is valid across all connected applications and contains identity, permission, and context information.

Cross-Application Session Sharing

Sessions are shared across applications. When a user logs into one application, they are effectively logged into all applications that trust Simezu's session state. Applications can query Simezu to validate sessions and retrieve current user context without requiring separate authentication.

High-Level Token Concepts

Simezu uses tokens to represent sessions and carry identity information. These tokens are issued by Simezu 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.

Session Lifecycle and Invalidation

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.

10. Security Principles

Authentication Security

Simezu 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 Enforcement

Authorization decisions are made centrally by Simezu, but enforcement happens in applications. Simezu 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.

Rate Limiting and Abuse Prevention

Simezu 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.

Auditability

Simezu 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.

11. Scalability & Architecture

Multi-App Scaling Philosophy

Simezu 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 Simezu's core systems. Each application integration is independent.

Stateless Integration Principles

Applications integrate with Simezu in a stateless manner. Applications do not maintain persistent connections or server-side state with Simezu. Instead, they make stateless requests for identity and authorization information as needed. This allows applications to scale independently and simplifies deployment.

Horizontal Scaling

Simezu 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.

Operational Assumptions

Simezu assumes that applications can make network requests to Simezu, network latency between applications and Simezu is acceptable for authorization queries, applications handle Simezu unavailability gracefully, and applications implement appropriate caching of authorization decisions when needed.

12. Extensibility

Modular Design Philosophy

Simezu 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.

Adding New Applications

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.

Evolving the Model

The permission model, ownership model, and other core concepts can evolve over time. Simezu 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.

13. Non-Goals & Limitations

What Simezu Intentionally Does Not Provide

Simezu 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.

Explicit Exclusions

Simezu excludes payment execution (Simezu 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 (Simezu does not provide stable external API contracts).

Misuse Patterns to Avoid

Do not use Simezu 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.

14. Glossary