Kimezu/Docs/Core concepts
Getting started · 02~10 minutes

Core concepts

The vocabulary of Kimezu in one page. Every other doc assumes you've read this — and after reading it, every other doc reads faster.

Identity

An identity is a single subject that exists across every connected application. Users authenticate once to Kimezu and are recognised everywhere; applications never hold credentials. The identity is the JWT's sub claim, and it's the only piece of the protocol that crosses tenant boundaries.

  • Stable — once issued, a sub never changes, even if the user changes email or display name.
  • Opaque — Kimezu IDs are UUIDs; nothing about the user is encoded in them.
  • Per-tenant scope — a user can sign into multiple tenants; they keep the same sub but the tenant claim disambiguates.

Sessions and tokens

A session is the authenticated state of an identity. Kimezu issues short-lived access tokens (JWTs, RS256-signed) carrying the session shape, and longer-lived refresh tokens (opaque) used to mint new access tokens. Applications verify access tokens locally against the JWKS — no per-request RPC.

SESSION   JWT payload
{
  "iss": "https://auth.your-tenant.eu",
  "aud": "app_abc123",
  "sub": "usr_8f2b3e1c",
  "tenant": "your-tenant",
  "actor_type": "user",
  "groups": ["editors"],
  "can": ["publish:article"],
  "payment_profile": "prf_default",
  "iat": 1715760000, "exp": 1715760900
}

Actor types

Every Kimezu session has one of three actor_type values:

  • "user" — a real person. Authenticates via password or magic link, optionally with MFA.
  • "group" — an organisational subject. Owns resources, holds payment profiles, but never logs in directly; sessions with actor_type: "group" are produced when a user acts on behalf of a group they belong to.
  • "agent" — a non-human identity (AI, automation, integration). Authenticates via API token; has an owner; scoped permissions can never exceed the owner's.

The session shape is the same for all three. Applications inspect actor_type only when they need to make a different decision for an agent (rate limits, UI suppression, additional logging).

Permissions and roles

Permissions are statements of the form "action:resource". They are evaluated centrally by Kimezu and the effective set is delivered on the session as the can claim. Permissions reach a user three ways:

  1. Direct grant — explicit user → permission edge.
  2. Role assignment — a role is a named bundle of permissions; assigning a role to a user grants its bundle.
  3. Group membership — a permission on a group propagates to all current members.

Revocation propagates the same three ways. Refresh tokens are invalidated on permission change so the effect reaches connected apps within the access-token lifetime (15 minutes by default), or immediately via push-revoke webhook.

Ownership

Ownership is the relationship between an actor and a resource. Kimezu doesn't store your resources, but it stores who owns them — because ownership affects two protocol-level decisions:

  • Authorization — owners typically have elevated permissions on their resources. Applications query Kimezu with the ownership context, not just the actor identity.
  • Payment routing — when a resource generates a payment, the recipient is the owner's payment profile. Group-owned resources pay the group.

Payments

A payment profile is a record of where money should be sent for a given actor. Each profile contains one or more provider configurations (Stripe, Mollie, PayPal), a country, and a VAT identity if applicable. Kimezu does not move money — it tells your application where the money should go.

Typical flow:

  1. Application asks Kimezu for the payment profile of the resource's owner.
  2. Application creates a charge using its own integration with Stripe / Mollie / PayPal, targeting that profile's account ID.
  3. Application reports the result back to Kimezu, including the buyer's country and lawful-basis context.
  4. Kimezu records the VAT treatment that applies and stores the record for invoicing and OSS reporting.

VAT and reverse-charge

Three VAT treatments are recorded at payment time:

  • VAT applied — EU consumer, or EU business without a valid VAT ID. Local rate added to the price.
  • Reverse charge — EU business with a valid VAT ID (verified against VIES). VAT not added; the buyer self-accounts in their own country.
  • Outside-EU scope — non-EU buyer. No EU VAT applies; the record states this explicitly.

Refunds inherit the original treatment. Quarterly OSS reports are generated in the legally required XML format plus a human-readable CSV.

Agents

Agents are non-human identities — bots, schedulers, AI processes — that need their own identity in the system. An agent has:

  • An owner (user or group) — the source of trust.
  • An API token — shown once at creation, never recoverable, instantly revocable.
  • A scoped permission set — always a subset of the owner's permissions.
  • An audience claim — which application(s) the agent can act against.

Agents authenticate against /v1/agents/token by presenting their API token; Kimezu returns a short-lived JWT with actor_type: "agent". The rest of the request flow is identical to user sessions.

Audit

Every protocol-level event is recorded in a tenant-scoped, HMAC-chained audit log. Each entry references the hash of the previous entry; the chain head is published hourly so any operator can verify integrity externally.

Events recorded include: sign-in, sign-out, MFA changes, permission grants and revokes, agent creation and revocation, tenant configuration changes, payment profile changes, and key rotations. Application-level events live in your application's own logs — Kimezu only records what crosses the protocol boundary.

Non-goals

For symmetry with the Platform · Non-goals section: Kimezu does not provide application UI, business logic, application data, payment execution, third-party SaaS integrations, or stable external API contracts for marketplaces. If your problem is in one of those buckets, Kimezu is the wrong tool.

← PreviousQuickstart