Entity reference

Target audience: Solution Architects, Enterprise Architects, Platform Implementers

Reading time: 25 minutes (full read), or jump to a specific entity

Prerequisites: The six-layer model

Introduction

This page is the canonical reference for the twelve entities of the deployment organization model. Each entity definition includes its purpose, key attributes, lifecycle considerations, and concrete examples.

For the layered structure that groups these entities, see The six-layer model. For their relationships and runtime composition, see Relationships and runtime flow.

Organizational entities

Deployment

A Deployment is a complete installation of ANKASecure©. It defines:

• The infrastructure footprint (compute, network, storage)
• The global compliance baseline (regulatory region, certification posture)
• HSM and KMS integrations (vendor, slots, partitions)
• Default cryptographic policies inherited by tenants

A Deployment maps to a productive environment, a regulatory region, or a logical infrastructure boundary. Organizations operating under conflicting regulatory regimes — for example, jurisdictions with incompatible cryptographic mandates — typically run separate deployments.

Key attributes:

When to define a separate deployment: when the regulatory or jurisdictional context differs in ways that require independent governance. A single multinational organization may run multiple deployments — one per major regulatory region — to satisfy data residency and sovereign cryptography requirements.

Tenant

A Tenant is an isolated cryptographic domain within a Deployment. It provides:

• Boundaries of key ownership
• Independent policy scope (within deployment baseline)
• Administrative separation
• Audit isolation

Each tenant owns its cryptographic assets and defines its own governance rules within the constraints imposed by the deployment. A compromise within one tenant cannot reach assets in another tenant, even when both run on the same infrastructure.

Key attributes:

Multi-tenancy scope: a Tenant is the unit of cryptographic isolation. It is also the natural unit of administrative delegation — different tenants can be administered independently. For details on the technical isolation mechanisms, see Multi-Tenant Isolation Model.

Application

An Application is a business system or functional domain. It defines:

• Business ownership
• Risk classification
• Regulatory scope
• Operational context

Examples: Core Banking, Card Issuance, CRM, Collections, Regulatory Reporting.

Key attributes:

Important distinction: Applications are not technical identities. They do not authenticate, do not hold credentials, and do not invoke operations directly. They are the business container under which technical actors operate. The technical identity is the Cryptographic Actor.

Application status is a runtime control over its actors. While an Application never authenticates itself, its status is a runtime governance lever, not mere metadata. Effective status is the logical AND over the containment chain tenant ∧ application ∧ actor (within an ACTIVE deployment): an actor may authenticate and operate only when its owning tenant, its owning application, AND the actor itself are all ACTIVE. Suspending an Application therefore immediately blocks every actor it contains — their M2M authentication is denied at token issuance (reason APPLICATION_NOT_ACTIVE), and any already-issued, still-valid JWT is denied at the Core API crypto seam and on scope-gated metadata reads (listKeys / viewKeyMetadata) with reason application-suspended.

Application status follows the same reversible/terminal distinction as the actor (below):

• SUSPENDED — reversible; the application (and therefore its actors) returns to service on reactivation. Suspension is a status flag on the application alone — it rewrites no child entity. The contained actors, grants, exchange contexts, exchanges, and keys are left untouched; effective status is re-composed by the AND over the containment chain at read time, and reactivation restores service instantly because nothing below was mutated.
• DISABLED — terminal; a DISABLED application cannot be reactivated. DISABLE does not revoke the actors' credentials (credential revocation is a separate, explicit lifecycle act).

DELETE is a terminal, irreversible cascade (distinct from SUSPEND). Where SUSPEND rewrites no child, deleting an Application (DELETE /api/v3/admin/tenants/{tenantId}/applications/{applicationId}, HTTP 204) drives every entity the application contains to its terminal state in a single best-effort cascade. There is no refuse-if-dependents guard: the presence of active Actors, Exchange Contexts, Cryptographic Exchanges, or Internal Crypto Use Cases does not block the delete. The cascade runs in dependency order:

1. Resolve the application's owned key identifiers (KIDs) first.
2. Revoke the application's Internal Crypto Use Cases.
3. Revoke the associated Capability Grants.
4. Close the Exchange Contexts.
5. Revoke the Cryptographic Exchanges (status REVOKED, soft-deleted).
6. Disable the Cryptographic Actors — including the application's non-deletable Default Actor, which is cascade-disabled here (its isDefault flag does not block the cascade).
7. Archive the application's non-shared keys.

Nothing is physically destroyed. The application's keys move to ARCHIVED — their material is retained, never destroyed. A key that is shared with another still-active aggregate is not archived; it keeps its real current lifecycle status. After the cascade, the retired application and its terminal children are removed from the active listings but remain inspectable through a read-only retired-applications surface (see the admin-api endpoints documentation). The terminal DELETE cascade is what makes the application.deleted propagation on the Cryptographic Actor and Cryptographic Exchange reachable — SUSPEND never reaches it.

Operational identity entities

Cryptographic Actor

A Cryptographic Actor is the operational subject that executes or requests cryptographic operations. It represents:

• An internal API service
• A batch processing job
• An integration channel
• A third party (for example, a card embossing vendor)
• A BPO processing system

Each Cryptographic Actor belongs to an Application, operates under defined constraints, and is the primary subject of authorization. Authorization decisions, audit events, and rate-limit enforcement are anchored on the actor.

Actors are the unit of trust at runtime. The model treats internal services and external parties uniformly: both are actors with clearly delimited capabilities.

Key attributes:

The six actor types, which are the complete persisted set:

Actor lifecycle: an actor is created when an integration is established, suspended when it is paused (without losing its authorizations), and disabled when the integration is terminated. Suspending the actor immediately blocks all of its grants without deleting them; reactivation restores the previous state. There is no REVOKED actor state — termination is DISABLED, and it is terminal.

Actor status is a runtime control (effective-status containment). The actor is the lowest leg of the effective-status containment chain tenant ∧ application ∧ actor (within an ACTIVE deployment). Suspending the actor — independently of its application's status — makes it effectively non-ACTIVE, which blocks:

• M2M authentication — the client_credentials grant is denied at token issuance (reason ACTOR_NOT_ACTIVE).
• Cryptographic operations — an already-issued, still-valid JWT is denied at the Core API crypto seam.
• Scope-gated metadata reads — listKeys / viewKeyMetadata are denied at the seam with reason actor-suspended (a status denial, never NO_GRANT).

The two control states are:

• SUSPENDED — reversible. The actor pauses without losing its grants or credentials; reactivation restores its effective status.
• DISABLED — terminal. A DISABLED actor cannot be reactivated (suspend/reactivate of a DISABLED actor returns HTTP 422). DISABLE does not revoke the actor's credentials — credential revocation is a separate, explicit lifecycle act.

The control is enforced at two points (defense-in-depth): the admin-api token-issuance gate (which denies the grant unless the whole containment chain is ACTIVE) and the core-api crypto seam (a fail-closed resolver that re-checks the live effective status on every operation and scope-gated read, so a JWT minted while the actor was ACTIVE stops working the moment the actor is suspended).

Default Actor and cascade-disable on application.deleted. Each Application auto-provisions a non-deletable Default Actor (isDefault = true) that cannot be deleted independently — an attempt to delete it on its own is refused. When its owning Application is terminally deleted, however, the Default Actor — like every other actor the application contains — is cascade-disabled as one step of the application's DELETE cascade; isDefault does not exempt it. This is the distinction the cascade resolves: the disable happens because the parent Application is being terminally deleted, not as an independent actor delete. See Application for the full ordered cascade.

Credential

A Credential is the authentication mechanism associated with a Cryptographic Actor. In the shipped platform there is exactly one mechanism: an OAuth 2.0 client_credentials pair — a client_id and a secret, persisted only as a hash. The plaintext secret is returned once, at issuance or rotation, and never again.

A Cryptographic Actor may hold multiple credentials simultaneously (for credential rotation), and credentials have independent lifecycle management. The separation between actor and credential allows secret rotation without altering authorization grants.

Key attributes:

Credential rotation pattern: an actor can hold an ACTIVE credential alongside a ROTATING_OUT one during a rotation window. The new credential is issued and tested in parallel with the old one, which keeps authenticating until its revoke_at elapses. No grant changes are required.

Disabling the actor does not revoke its credentials. The two are independent lifecycle acts, which is exactly why a deprovisioning cascade revokes the credential explicitly rather than relying on the actor transition to do it.

ROTATING_OUT intermediate state: when a rotate operation specifies a positive graceWindowHours (default 24h, max 720h), the previous credential transitions from ACTIVE to ROTATING_OUT with revoke_at = now + graceWindowHours. A ROTATING_OUT credential continues to authenticate until revoke_at elapses — this is the entire point of the grace window. A scheduled finalization task in ankasecure-admin-api sweeps ROTATING_OUT rows on a fixed cadence (default 60s) and transitions them to REVOKED when their revoke_at is in the past. When the rotate operation specifies graceWindowHours = 0 (INLINE hard cutover), the previous credential transitions directly to REVOKED in the same transaction as the new credential's INSERT — no ROTATING_OUT row is ever observable by a concurrent reader.

Governed exchange entity

Exchange Context

An Exchange Context is a governed interaction scenario involving cryptographic operations. It models:

• The relationship between parties
• The purpose of the exchange
• The direction of data flow
• The trust model

Examples:

• Card Embossing — VISA
• Card Embossing — AMEX
• Collections Processing — BPO Alpha
• Regulatory Reporting — Central Bank
• Internal Analytics Pipeline

Key attributes:

Why this entity exists: the Exchange Context distinguishes ANKASecure© from a traditional KMS. By modeling the business interaction explicitly, authorization decisions can reflect not only who is acting and what they are doing, but the governed business relationship in which the action takes place.

The four states:

The terminal state is CLOSED. Earlier revisions of this page called it TERMINATED; no such value exists, and PENDING_ACTIVATION was missing entirely.

Lifecycle implication: when a third-party relationship is renegotiated or terminated, the cryptographic implications propagate through the affected Exchange Context. Suspending or closing a context affects every grant scoped to it — without requiring per-grant inspection.

Cryptographic resource entities

Cryptographic Asset

A Cryptographic Asset is managed cryptographic material. Types include:

Each asset belongs to a Tenant, is governed by policy, and follows a lifecycle that is two-dimensional: a stable alias (the KID identity) and the material versions underneath it each carry their own status, and what the API publishes as the key's status is a projection of the pair. The nine published tokens and how they are produced are set out in Asset lifecycle below.

Key attributes:

Asset identification: assets are referenced by stable KID. The runtime resolves the appropriate version based on policy, lifecycle state, and operation type. This is the foundation of the KID system.

Asset lifecycle — two dimensions, one projection

An asset is not a row with a status column. It is a stable alias plus the material versions recorded under it, and each dimension has its own state machine. Rotation advances the material while the alias — and therefore the KID every grant and every ciphertext refers to — stays constant. That is the whole point of the KID system, and it is why a flat single-status reading of a key is wrong.

Dimension 1 — the alias (the KID identity). Four states:

(creation) -> ACTIVE
ACTIVE     -> SUSPENDED         (incident investigation)
SUSPENDED  -> ACTIVE            (incident cleared)
ACTIVE     -> RETIRED           (decommission or revoke)
SUSPENDED  -> RETIRED           (compromise confirmed)
RETIRED    -> DELETED_LOGICAL   (retention elapsed + operator delete)

Dimension 2 — each material version. Six states, with at most one PRIMARY per alias at any time:

PENDING_PRIMARY     -> PRIMARY              (atomic rotation activation)
PENDING_PRIMARY     -> DESTROYED            (operator cancels the rotation)
PRIMARY             -> RETIRED              (a rotation supersedes it)
PRIMARY             -> REVOKED              (alias revoke cascade)
RETIRED             -> REVOKED              (operator revokes this material)
RETIRED | REVOKED   -> PENDING_DESTRUCTION  (operator marks for destruction)
PENDING_DESTRUCTION -> RETIRED | REVOKED    (cancel-destruction restores the prior state)
PENDING_DESTRUCTION -> DESTROYED            (cooling-off elapsed, operator deletes)

The projection. The published key status is computed from the alias and its current PRIMARY material, evaluated strictly in this order:

Two consequences of the table that a flat list conceals:

• archived is not a persisted status. It is a derived label: an alias in RETIRED whose revocation metadata has been cleared. Archiving is precisely the act of clearing that metadata — which is why archiving is only reachable from revoked, and why archived and revoked are the same alias state distinguished solely by whether a cause is recorded.
• pending_rotation and rotated are never emitted at the kid level. They belong to the material dimension, where the corresponding states are PENDING_PRIMARY and RETIRED. The projection above has no branch that can produce either token for a key, so no client should switch on them.

Archiving is not data-denying. Under the default lifecycle policy an archived key still permits decrypt and verify; what it stops permitting is encrypt and sign. This is the same semantics AWS, GCP and Azure KMS apply to a disabled or retired key, and it is what makes a decrypt-only authorization over an archived key a legitimate data-recovery shape rather than a misconfiguration.

The destruction chain and its cooling-off gate

Destroying key material is a deliberate, multi-step, temporally gated cycle. It is never a side effect of another action, and no administrative action on an authorization construct — deleting a grant, revoking a use case, deleting an Application — enters this chain at any point.

stateDiagram-v2
    [*] --> active
    active --> revoked: POST /revoke (cause recorded)
    revoked --> archived: POST /archive (cause cleared)
    archived --> pending_destruction: POST /mark-for-destruction<br/>(sets destructionEligibleFrom = now + coolingOffDays)
    pending_destruction --> archived: POST /cancel-destruction
    pending_destruction --> deleted_logical: DELETE<br/>(only after destructionEligibleFrom)
    deleted_logical --> [*]

Each transition is guarded, and the guards are the point:

The cooling-off window is a temporal gate, not advice: a DELETE issued before destructionEligibleFrom is refused, and the refusal names the timestamp at which the key becomes eligible. The window exists so that an irreversible act has a period in which it can be reconsidered — which is also where a warning belongs when other constructs still reference the key.

DELETED_LOGICAL is the end of the published lifecycle: the KID cannot be revived, and no authorization may be composed over it. The identity is however retained for audit, and because the uniqueness constraint on a KID applies only to live aliases, the same KID may be created again afterwards — a fresh key with a fresh identity that happens to reuse the name.

Purpose projection on import (Origin = IMPORTED): every Asset has a single KeyPurpose (ENCRYPT_DECRYPT or SIGN_VERIFY) — its permitted operations never span both families. When an Asset originates from a legacy JKS/PKCS#12 import, its purpose is derived from the certificate X.509 KeyUsage or declared explicitly; an ambiguous key cannot be imported as a single dual-capable Asset. A genuinely dual-use legacy keypair is projected onto two single-purpose Assets (<kid>-enc and <kid>-sig) over the same key material, each with its own material version. The precedence that decides an alias's purpose is declared on the import request itself, POST /api/v3/admin/tenants/{tenantId}/keys/import-keystore.

Capability

A Capability is a cryptographic function that can be executed. Capabilities abstract the use of cryptographic material into controlled operations.

Standard capabilities:

Why capabilities matter: a consumer never receives a key; it requests the execution of a capability and receives the operational result. This abstraction enables crypto-agility — the underlying algorithm or key version can change without affecting consumers.

For the broader principles behind this design, see Policy-Driven Crypto-Agility.

Control entities

Capability Grant

A Capability Grant is the authorization given to a Cryptographic Actor to invoke one or more capabilities under specific conditions. It binds:

• An Actor
• A set of Capabilities — the field is a list, and a grant that authorizes two functions carries both in one record
• One or more Cryptographic Assets
• An Exchange Context (optional or required, depending on the use case)
• Constraints

In practice most grants carry a single capability: an orchestrated use case declaring [ENCRYPT, DECRYPT] emits two grants, one carrying ["ENCRYPT"] and one carrying ["DECRYPT"], not one grant carrying both. The multi-capability shape is what makes the cross-kid capabilities expressible: REENCRYPT is a first-class capability over a pair of assets — stored in the order given, source-first by convention, though that order is a recording convention rather than a control — and it does not decompose into, or imply, a standalone DECRYPT on the source key.

A Capability Grant answers four questions in a single record:

1. Who can act? — the Actor
2. What can they do? — the Capability
3. On what assets? — the Cryptographic Assets
4. Under what conditions? — the Constraints, scoped to an Exchange Context

Key attributes:

Why this is the unit of authorization: revoking a grant immediately removes the actor's ability to invoke the capability, without affecting other grants or other actors. The grant is the smallest unit of fine-grained governance.

Constraint Policy

A Constraint Policy expresses restrictions on how a capability can be used. It is a named, reusable tenant-level entity with four enforced dimensions, not a typed parametric object — a single policy row carries all four fields, and any subset of them may be left unset.

Key attributes:

Composability: the four dimensions compose by conjunction — all populated ones must be satisfied for the grant to authorize. A grant may be simultaneously time-windowed (valid within a stated period), usage-capped (at most 50,000 invocations) and rate-limited (at most 500 per minute). A Constraint Policy is a tenant-level entity referenced by grants; the relationship is N:1, so one policy may govern several grants.

Policy

A Policy is a global or scoped rule that governs platform behavior. Policies exist at multiple levels:

• Deployment — regulatory region, allowed algorithms, FIPS posture
• Tenant — tenant-specific algorithm catalog, lifecycle defaults
• Exchange Context — rules specific to a business interaction
• Cryptographic Asset — rotation cadence, usage limits, exportability
• Capability — invocation rules, audit requirements

What policies define:

Key attributes:

Policy versus Constraint Policy: Policies govern platform behavior at architectural levels and apply to many grants. Constraint Policies govern individual grants. The two are complementary: a Policy may say "ML-DSA-87 is the required signature algorithm for the Treasury tenant"; a Constraint Policy may say "this specific grant is single-use and expires in 4 hours."

For the broader policy framework, see Policy-Driven Crypto-Agility.

Evidence entity

Audit Event

An Audit Event records every cryptographic operation and every authorization decision. Each event captures the full context of what happened.

Captured fields:

Integrity: audit events are HMAC-SHA256-signed at production time over the whole event envelope (metadata canonical fields plus the payload type's own canonical field list) and stored in an isolated audit data store. Tampering is detectable; events are immutable once produced.

Both allow and deny: the evidence layer captures the full decision context, not only successful operations. A denied invocation produces an audit record with the reason for denial, supporting forensic analysis and continuous monitoring.

What audit events enable: compliance reporting (DORA, PCI-DSS, SOX, GDPR), incident response, forensic reconstruction, continuous posture monitoring, and detection of anomalous patterns.

Control plane orchestration entities

The 12 entities above form the runtime authorization model. Core API runtime authorization resolves against Capability Grant and never references the orchestration layer described here.

The platform also exposes one control-plane orchestration entity that lives strictly above the runtime model and exists for administrative usability. The runtime model is unaffected by anything in this section.

Cryptographic Exchange

A Cryptographic Exchange is an admin-managed aggregate that groups one Application + one Cryptographic Actor + one Cryptographic Asset (by KID) + one Exchange Context + one Constraint Policy under a single managed lifecycle. It owns its Capability Grant 1:1.

Where the runtime model asks "is this Actor authorized to invoke this Capability on this Asset?", the orchestration model answers a different question for the admin: "what is this whole intercambio I am setting up, and where is it in its lifecycle?". The 7-step manual onboarding sidebar (Applications → Actors → Contexts → Constraint Policies → Capability Grants) is replaced by a single tabbed wizard that materializes one Exchange.

Lifecycle states:

Cascade from application.deleted (end-to-end). When an Application is terminally deleted, each Cryptographic Exchange it references transitions to REVOKED and is soft-deleted as one step of the application's irreversible DELETE cascade — alongside revoking the application's Internal Crypto Use Cases and Capability Grants, closing its Exchange Contexts, disabling its Cryptographic Actors (including the non-deletable Default Actor), and archiving its non-shared keys (material retained, never destroyed). The cascade is terminal and best-effort; it never refuses on the presence of active dependents. This is the behaviour that makes the application.deleted transition above reachable. See Application for the full ordered cascade.

Key attributes:

Composition vs reference (key invariant):

• Composes (1:1, owned): the Capability Grant. The 1:1 invariant is enforced at the database layer via a UNIQUE constraint on grant_id. Two Exchanges cannot share a Grant.
• References (N:1): Application, Actor, Asset (by KID), Exchange Context, Constraint Policy. These remain reusable across multiple Exchanges. The same Actor can participate in many intercambios.

Why this entity exists: the orchestration layer collapses the admin's mental model from "5 separate entities I have to wire correctly" into "one Exchange I am setting up". Activate / Suspend / Resume / Revoke act on the Exchange and propagate atomically to the underlying Grant. The runtime authorization path (Core API) does not change — it still resolves against the Grant. The orchestration is purely an admin usability layer.

API: the Cryptographic Exchange is exposed by ankasecure-admin-api under /api/v3/admin/exchanges. See the admin-api endpoints documentation for the full surface (list, detail, create, PATCH, validate, activate, suspend, resume, revoke, clone, audit-trail).

Greenfield posture: ANKASecure has no live data to migrate. The schema lands empty at first deployment via the 02e_cryptographic_exchange.sql init-sql script. Demo data alignment is operational tooling in the provision-demo workspace project, which wraps any seed Capability Grants in an owning Exchange to maintain the 1:1 invariant.

Quick reference table

Next steps

• For relationships between these entities and the runtime decision flow, see Relationships and runtime flow.
• For worked examples that show these entities composed in real scenarios, see Reference scenarios.
• For the broader architectural context, return to Deployment organization model — Overview.