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 thirteen entities documented here: the twelve entities of the deployment organization model, plus the single control-plane orchestration entity that sits above it. 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. Each key is retired according to its current status and is never revoked twice: an active or expired key is revoked for ADMINISTRATIVE and archived; a suspended key is revoked and archived — for SECURITY_COMPROMISE when that is its suspension cause, so a key held for a security compromise stays sealed, and for ADMINISTRATIVE otherwise; a revoked key is archived keeping its cause; an archived or pending_destruction key is left as it is. 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 interoperability and migration planes — interoperability.encrypt, interoperability.verifySignature, migration.convertPkcs7 and migration.analyzePkcs7 are denied at the same seam, across six handlers: each PKCS#7 operation carries a streaming twin on the same scope. The interoperability operations and migration.analyzePkcs7 use no tenant key and take no Capability Grant decision, so for them the containment check is the only thing that closes them. A PKCS#7 → JOSE conversion (migration.convertPkcs7, buffered and streaming) does use tenant keys: after the containment check it also takes a Capability Grant decision per leg — REENCRYPT from the opening recipient to every recipient (its own pair included) and RESIGN from every signer to itself — so a suspended actor is refused before any grant is charged.

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. The platform persists three kinds, recorded on actor_credentials.kind:

• CLIENT_SECRET — an OAuth 2.0 client_credentials pair: a client_id and a secret held only as a hash. The plaintext is returned once, at issuance or rotation, and never again.
• PRIVATE_KEY_JWT — a registered public key (JWK). The actor proves possession of the private half by signing a client assertion; the platform stores no secret at all.
• FEDERATED_JWT — the actor is bound to an external issuer and subject, and authenticates with a token that issuer minted. Federated identity therefore applies to Cryptographic Actors as well as to human users.

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  (approval of a destruction request)
PENDING_DESTRUCTION -> RETIRED | REVOKED    (cancel-destruction restores the prior state)
PENDING_DESTRUCTION -> DESTROYED            (cooling-off elapsed, the platform's destruction executor)

The projection. The published key status is computed from the alias and its representative material — the current PRIMARY when the key has one, otherwise (a revoked, archived or pending-destruction key) a deterministic representative of its non-destroyed versions, preferring a PENDING_DESTRUCTION version and then the highest version number. The key list, the single-key read and the lifecycle guards all use this one rule, so they never disagree on a key's status. It is 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 archived_at is set. Archiving is the act of recording archived_at / archived_by — which is why archiving is only reachable from revoked, and why archived and revoked are the same alias state distinguished solely by that timestamp. Both carry the revocation cause: a RETIRED alias always has one, and archiving keeps it.
• 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 — the cause is. Archive keeps the cause the key was revoked for: under the default lifecycle policy an archived key revoked for any cause other than SECURITY_COMPROMISE still permits decrypt and verify, while one revoked for SECURITY_COMPROMISE stays sealed on every plane; what archiving itself 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 kept, archivedAt set)
    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: no caller can destroy the key, and the platform destroys it only once the window has ended. 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 removes the actor's ability to invoke the capability without affecting other grants or other actors, and it also removes the operation scope the grant derived into that actor's tokens — no role row is written, so nothing has to be unwound. Removal is bounded rather than instant: up to the 900 s access-token lifetime, plus up to 300 s of enforcement-plane grant cache. 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:

A policy is a template; a grant enforces a version of it. Every write of a Constraint Policy is an immutable version. A grant pins the version current when it is issued — an Exchange's grant at activation, a standalone grant at creation, a use case's grants when it is provisioned — and enforces that version's limits for its whole life. Editing the policy therefore changes only grants issued afterwards: an active grant keeps the limits it was issued under, and a consumed single-use grant stays consumed even if revokeOnUse is then unticked. To change an active grant's limits, issue a new grant (clone and activate its Exchange; revoke and re-create a standalone grant). The crypto audit row of every grant decision names the pinned pair (constraintPolicyId, constraintPolicyVersion).

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 defined above this section — every entity on this page except the one that follows — 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:

A terminal Exchange (EXPIRED, CONSUMED, REVOKED) cannot be suspended, resumed, edited or re-entered; clone it to issue a new grant, which pins the policy's current version on activation.

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

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 Exchange Management for the full surface (list, detail, create, PATCH, validate, activate, suspend, resume, revoke, clone), including the mandatory operator justification that suspend and revoke require.

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.