PH-01 — Tenant Identity and Access¶

Payment Hub · Working Draft · Revised Working Copy v5 · Updated September 3, 2026

1. Objective¶

Provide the shared identity, Tenant isolation, and access-control behavior required for DragonPay capabilities to safely determine:

which Tenant a request belongs to;
who or what is acting;
what that caller is permitted to do; and
whether the requested access is currently allowed.

PH-01 establishes the trusted authorization context used throughout DragonPay. It does not prescribe a fixed identity-provider architecture, authentication protocol, caller taxonomy, token format, user database, or authorization framework.

The Product requirement is that DragonPay can reliably authenticate or trust approved caller identity, enforce Tenant and permission boundaries, revoke or suspend access when required, and retain sufficient audit evidence for material access and administration activity.

2. Tenant boundary¶

A Tenant represents a participating DragonPay customer organization and is the primary customer-data and authorization boundary.

DragonPay must:

assign each Tenant a stable DragonPay identity;
prevent one Tenant from accessing or acting on another Tenant's protected data or payments unless explicitly authorized privileged cross-Tenant access permits it;
preserve Tenant identity on historical payment, configuration, audit, and operational records;
determine whether a Tenant is currently permitted to operate on the platform;
allow Tenant access to be suspended without deleting or reassigning historical information; and
preserve historical attribution if a Tenant relationship later ends.

Privileged cross-Tenant access is DragonPay-operational access authorized for a DragonPay identity acting under its own authority — it does not introduce delegated-user access, impersonation, or a support-session workflow.

The exact Tenant lifecycle status values are not a Product requirement unless future behavior requires additional distinct states.

Product-specific readiness or activation belongs to PH-02 and the applicable Payment Product. PH-01 does not create a separate onboarding workflow.

Environment is deployment/infrastructure context, not a Tenant business attribute.

3. Trusted caller identity and context¶

DragonPay must establish a trusted caller identity and authorization context for any request that requires authorization.

That context must contain or securely reference enough verified information for the receiving capability to determine, as applicable:

Tenant scope;
acting identity/principal;
granted authority or permissions;
originating application/channel or authentication context when relevant; and
correlation/audit context needed to explain the action.

The context must be derived from a trusted authentication or service-to-service relationship and must not be accepted merely because caller-supplied fields claim a Tenant or permission.

Initial caller sources are expected to include examples such as:

DragonPay operational/workforce users;
participating-CU operational/workforce users;
DragonPay or CU applications/services; and
CU-authenticated members acting through an approved channel.

These are known initial caller sources, not a closed Product taxonomy. Future trusted caller types may use the same authorization model without requiring PH-01 to introduce a new Product identity class.

PH-01 does not require separate Product entities such as WorkforceUser, ApplicationIdentity, or ApiClient unless an implementation or later Product behavior needs those distinctions.

4. Roles, permissions, and assignments¶

DragonPay must support controlled roles and permissions sufficient to authorize the operational and system behavior required by implemented Products and experiences.

For the initial implementation:

DragonPay must support a small set of predefined roles and permission bundles;
authorized administrators can assign and remove those roles within their permitted scope;
a caller's effective permissions must be determined from authoritative access configuration;
role/permission changes must take effect without requiring payment records to be rewritten; and
user-created custom roles or a general role/permission designer are not required.

OX-01 may provide the human administration experience for role assignment, but PH-01 remains authoritative for whether the assignment is valid and what access it grants.

The exact role names, permission storage model, hierarchy, policy engine, and authorization library are Engineering/Product-operations implementation details unless a future Product requires a particular distinction.

5. Authorization behavior¶

Every protected DragonPay capability must enforce authorization using trusted context and authoritative access rules.

At minimum:

Tenant-scoped operations require authorization for the applicable Tenant;
privileged DragonPay cross-Tenant access requires explicit authority;
possession of an identifier does not grant access to the referenced resource;
UI visibility does not grant permission — backend authorization remains authoritative;
a caller cannot expand its own Tenant scope or permissions through request data;
suspended/revoked access must not continue to authorize new protected actions;
authorization failure must not leak protected cross-Tenant data; and
payment execution or other high-impact operations may apply additional Product/domain authorization beyond PH-01 access checks.

For end-user/member callers, the trusted context must identify the acting principal sufficiently for the owning capability to enforce resource-level entitlement. PH-01 does not determine whether that principal is entitled to a specific payment, account, instrument, or other domain resource; that decision remains with the capability that owns the resource or Product behavior.

PH-01 answers whether the caller is allowed to invoke a capability within a scope. The owning Product/domain capability still determines whether the requested business action is currently valid.

6. Suspension and revocation¶

DragonPay must be able to prevent further protected access when a Tenant, caller, application/service relationship, or role assignment is no longer authorized.

Suspension or revocation must:

stop newly attempted protected actions within the affected scope;
preserve existing payment and audit history;
avoid rewriting historical caller attribution; and
remain distinguishable from normal payment/business failure.

Suspension or revocation must become effective within a defined maximum propagation period appropriate to the access risk and must not rely solely on natural expiration of an existing session, token, or credential. The specific bound and enforcement mechanism are Engineering/security decisions.

The exact mechanism for token invalidation, session termination, credential rotation, cache expiry, or identity-provider revocation is Engineering/security implementation.

PH-01 does not require a dedicated Product-level revocation workflow or universal revocation-state taxonomy.

7. Access administration and audit¶

Material identity/access administration and privileged access must produce durable audit evidence sufficient to establish:

who or what performed the action;
affected Tenant/scope;
material action performed;
affected identity/role/resource when applicable;
outcome;
time; and
correlation or supporting context needed for investigation.

Examples of material auditable activity include:

Tenant access changes;
role assignment/removal;
caller/application access suspension or restoration;
privileged cross-Tenant access; and
other access-control changes that materially affect who can use DragonPay.

The exact audit-event schema, persistence mechanism, taxonomy, retention implementation, and search/index design are not prescribed by PH-01. Retention requirements for this audit evidence follow applicable DragonPay security/compliance policy or standard rather than a PH-01-defined duration.

Payment lifecycle history remains owned by the applicable payment/history capabilities and should not be conflated with access-administration audit.

8. Product stories¶

PH01-01 — Establish and Protect Tenant Scope¶

Objective

Maintain a stable Tenant boundary that other DragonPay capabilities can rely on for isolation and authorization.

Required behavior

Give each Tenant a stable DragonPay identity.
Determine whether the Tenant is currently permitted to operate.
Enforce Tenant isolation for protected data/actions.
Support suspension of Tenant access without deleting historical records.
Preserve Tenant attribution after suspension or relationship termination.
Keep Product activation/readiness outside PH-01.

Acceptance

One Tenant cannot access another Tenant's protected resources without explicitly authorized privileged access.
A suspended Tenant cannot initiate newly protected Product operations.
Suspending or ending access does not erase or reassign historical payment/audit records.

PH01-02 — Establish Trusted Caller Context¶

Objective

Give protected DragonPay capabilities trustworthy information about who or what is acting and within what scope.

Required behavior

Establish caller identity from an approved trusted authentication/service relationship.
Supply or securely reference the Tenant and authority information required by the receiving capability.
Support the initial caller sources required by DragonPay/CU operations, services/applications, and CU-authenticated member channels.
Do not treat caller-provided Tenant/permission claims as trusted merely because they are present.
Allow future caller types without requiring a closed PH-01 identity taxonomy.

Acceptance

A protected capability can identify the authorized Tenant and acting caller/principal.
Spoofed caller-supplied Tenant/permission data cannot expand access.
Workforce, service/application, and CU-member channel callers can all be represented without requiring separate Product identity entities unless their behavior actually differs.
The caller context does not itself decide whether the requested payment/business action is valid.

PH01-03 — Assign and Enforce Access¶

Objective

Allow authorized DragonPay/CU administration to grant only the access needed for supported operations.

Required behavior

Support predefined roles/permissions needed by implemented Products and operational experiences.
Allow authorized assignment/removal of those roles within the permitted scope.
Derive effective caller authority from authoritative access configuration.
Enforce that authority on protected backend operations.
Support privileged cross-Tenant access only when explicitly authorized.
Do not require user-created custom roles or a general permission designer initially.

Acceptance

OX-01 can administer the predefined roles needed for the initial operating model.
Removing an assignment prevents subsequent unauthorized protected actions.
UI controls cannot bypass backend permission checks.
A caller cannot grant itself permissions outside its administrative authority.

PH01-04 — Suspend or Revoke Access¶

Objective

Stop future protected access when authorization is removed while preserving historical integrity.

Required behavior

Support suspension/revocation of applicable Tenant/caller/application/role access.
Prevent new protected actions once the access change is effective.
Preserve prior payment and audit attribution.
Leave session/token/credential invalidation mechanics to the implementation.

Acceptance

Revoked/suspended access no longer authorizes new protected requests.
Existing payment records remain intact.
Historical actions continue to identify the original caller/scope.

PH01-05 — Audit Material Access and Administration¶

Objective

Provide durable evidence for material identity/access changes and privileged use.

Required behavior

Record material access-administration actions and privileged access.
Preserve caller, Tenant/scope, action, outcome, time, and useful correlation context.
Protect audit information according to authorization.
Keep access-administration audit distinct from payment lifecycle history.

Acceptance

Role/access changes can be attributed to the actor that performed them.
Privileged cross-Tenant access is auditable.
Audit evidence cannot be altered through ordinary operational use.

9. Engineering-owned / intentionally non-prescribed detail¶

PH-01 intentionally does not prescribe:

a fixed Tenant lifecycle enum;
DRAFT, ACTIVE, SUSPENDED, or RETIRED as mandatory status values;
separate Product entities for workforce users, application identities, API clients, or every possible caller type;
a closed caller-type taxonomy;
identity-provider vendor;
OAuth/OIDC/token/session protocol details;
exact token claims;
user/application persistence schema;
exact role names or role hierarchy;
custom-role designer;
exact permission storage/evaluation mechanism;
middleware/library architecture;
token/session-revocation implementation;
authentication-service decomposition;
exact audit-event schema/taxonomy;
audit database/storage technology;
administrative UI design; or
implementation sequence.

Engineering should use established identity, authentication, authorization, Tenant-isolation, service-identity, and audit patterns appropriate to the selected infrastructure and integrations.

Useful technical identity/access ideas from earlier PH-01 versions may be retained as non-authoritative Engineering reference material where helpful.

10. Scope boundaries¶

PH-01 owns¶

stable Tenant identity and Tenant isolation;
trusted caller identity/context needed for authorization;
shared roles/permissions and their assignment;
access enforcement;
suspension/revocation behavior; and
material identity/access administration audit.

Out of scope¶

Product-specific activation/readiness.
Payment/customer eligibility.
Payment workflow/action authorization beyond shared caller access.
Party/customer identity master data.
CU member authentication itself.
Customer account ownership/entitlement logic.
Generic identity-governance/access-review platform.
Delegated support/impersonation workflow in the initial scope.
Custom role/permission designer.
Infrastructure/environment modeling as business data.

11. PH-01 completion criteria¶

PH-01 is complete for the initial Product scope when:

every participating Tenant has a stable DragonPay identity and protected Tenant boundary;
DragonPay can determine whether a Tenant is permitted to operate and can suspend its access without losing historical attribution;
protected capabilities receive trusted caller/Tenant/authority context from approved authentication or service relationships;
the model can support DragonPay/CU workforce callers, services/applications, and CU-authenticated member channels without treating those examples as a closed Product taxonomy;
predefined roles/permissions required by OX-01 and implemented Products can be assigned and enforced;
user-created custom roles/general role designer are not required;
CU users/callers cannot access another Tenant's protected resources;
privileged cross-Tenant DragonPay access requires explicit authority and is auditable;
revoked/suspended access cannot continue to authorize new protected actions;
payment and historical audit records survive access suspension/relationship termination unchanged;
material access/admin actions produce durable audit evidence; and
Engineering remains free to choose the identity provider, caller representation, token/session model, role implementation, authorization framework, audit schema, and other internal mechanics while preserving these behaviors.