Security Credentials

Key Management

Lifecycle governance for your cryptographic secrets and authorization tokens.

2.5 Key Management Configuration Rules

POEMS supports master keys, access keys and authorization codes. Keys must be rotated periodically based on policy.

Master Key: Root credential generated by Super Admin only.
Access Keys / AccessKeyId: Used for API request integrity and identification.
Auth Codes: Used for transaction classification / segmentation.
Signing Keys: Used for request non-repudiation where applicable.
mTLS Certificates: Used as the system identity for FI-to-Payvala connectivity.

Management Dashboards

Master Key Dashboard

Add New

Add New opens the master key creation flow. After save, the next screen shows the generated record with status and timestamps.

Regenerate / Deactivate

These actions rotate or retire the selected master key and then return to the dashboard with updated status labels.

Access Key Dashboard

Activate / Deactivate

Clicking these buttons changes whether an access key can sign API traffic; the table refreshes with the new state after completion.

Retire

Retire permanently removes the key from active use and the next visible state is the retired status in the same listing.

Auth Codes

Add New Auth Code

This opens the auth-code creation form used for transaction classification, then returns to the auth-code table after save.

Refresh

Refresh reloads the latest key and auth-code status from POEMS without changing any existing configuration.

Key Types Explained

Master Key
The root credential for your institution. Only Super Admins can generate this. Used to bootstrap system identity.
Access Key ID
Public identifier sent in the x-access-key-id header for every API request.
Access Key (Secret)
Private shared secret used to calculate HMAC-SHA256 signatures. Never shared via API; only displayed once on generation.
Auth Code
A business-level token used to segment transactions (e.g., by merchant type or region). Mandatory for all transaction notifications.

Dashboard Actions

Generate New: Immediately invalidates the previous key (if configured without overlap) and provides a new secret.
Revoke / Retire: Permanently disables a key. Use this in case of credential compromise.
Download JWKS: Exports the public key set required for payload encryption (JWE/JWS).

Responsibility Matrix

FI Responsibility Payvala Responsibility
Store all secrets and private keys in an HSM or hardware-backed secrets manager. Issue platform credentials and manage key status changes.
Never hardcode secrets or store them in plaintext configuration files. Enforce key expiry, rotation and revocation rules.
Implement rotation and overlap windows to prevent downtime during key changes. Provide key lifecycle visibility in POEMS (expiry, status, timestamps).