Skip to main content
This guide walks through every step an Issuer needs to support the Compliance Access Key (CAK) framework: enabling CAK in the Dashboard, integrating with the Issuance SDK to obtain the public key, encrypting sensitive user data, and implementing the callback endpoint that receives authorization notifications.
Before starting, make sure you understand the CAK lifecycle overview.

​
Issuer responsibilities summary

ResponsibilityDescription
CAK feature configurationEnable CAK for pricing schemas and issuance programs in the Dashboard
Callback URL setupConfigure a global HTTPS callback endpoint
Data encryption integrationUse the Issuance SDK to obtain the CAK public key and encrypt user data
Callback endpoint implementationImplement an HTTPS endpoint that handles authorization notifications
Callback business routingRoute callback requests by schemaId to your business logic

​
Step 1: Dashboard configuration

​
Enable CAK on a pricing schema

In the Developer Dashboard, navigate to your pricing schema configuration. Enabling CAK here is the top-level switch that determines whether CAK-encrypted credentials can be created under this pricing model.

​
Enable CAK on an issuance program

When creating or editing an issuance program, enable the CAK feature. When enabled:
  • The Issuance SDK generates a CAK key pair during credential issuance
  • The SDK returns the CAK public key to your backend system
  • Your system is expected to encrypt the user’s raw sensitive data with this key
When disabled, the issuance flow operates identically to standard credential issuance.

​
Configure a global callback URL

Set a global HTTPS callback URL that receives notifications whenever a Verifier is authorized to access data from credentials you have issued. 
POST /issuer/modify

{
  "callbackUrl": "https://your-domain.com/api/cak/callback"
}
This is a single, global endpoint for all your issuance programs. Your implementation must route incoming requests to the correct business logic based on the schemaId in the callback payload.
The callback URL must be highly available. The platform includes retry logic, but prolonged downtime means you miss authorization notifications.

​
Step 2: Issuance SDK integration

When CAK is enabled for an issuance program, the issueCredential() call returns a cakPublicKey in its response. 
const result = await airService.issueCredential({
  authToken,          // Partner JWT with scope=issue
  issuerDid,          // Your Issuer DID
  credentialId,       // Issuance program ID
  credentialSubject,  // User's credential claims
  curve: "secp256r1", // Optional: elliptic curve (default: secp256r1)
});

const { cakPublicKey } = result;
ParameterTypeRequiredDescription
authTokenstringYesPartner JWT with scope=issue
issuerDidstringYesYour Issuer DID
credentialIdstringYesIssuance program ID
credentialSubjectRecord<string, unknown>YesCredential claims and attributes
curve"secp256r1" | "secp256k1"NoElliptic curve for key generation. Defaults to secp256r1 (P-256)
Response:
FieldTypeDescription
cakPublicKeystringCAK public key for encrypting the user’s sensitive data. Only returned when CAK is enabled for the issuance program.
The public key is deterministically derived from the [User - Issuer - Schema] composite identifier. The same key is returned for the same combination, so you can retrieve it without re-issuing the credential.

​
Step 3: Encrypt and store user data

After receiving the cakPublicKey, encrypt the user’s raw sensitive data before storing it.

​
What to encrypt

Encrypt any raw PII or biometric data associated with the credential:
  • Identity document images (ID cards, passports)
  • Facial biometric photos
  • Full names, dates of birth, document numbers
  • Any other data that verifiers may need for compliance review

​
Encryption scheme

Use ECIES (Elliptic Curve Integrated Encryption Scheme) with the CAK public key:
PropertyValue
SchemeECIES
CurveSECP256R1 (P-256) by default
InputCAK public key + raw user data
OutputEncrypted ciphertext

​
Storage

Store the encrypted ciphertext in the designated storage system (dStorage on Moca Chain). The encrypted data cannot be read by anyone — including your own systems — without the corresponding CAK private key, which is only generated when a Verifier obtains user consent during verification.

​
Step 4: Implement the callback endpoint

When a user authorizes a Verifier to access their data, the platform sends an HTTPS POST to your configured callback URL.

​
Callback payload

The payload includes fields that identify who authorized whom, for which credential schema:
FieldDescription
userIdThe user who granted authorization
verifierDidThe DID of the Verifier that was authorized
schemaIdThe credential schema involved
The callback serves as an authorization event notification and audit signal only. It does not contain encrypted data, cryptographic keys, or any information that enables data decryption.

​
Implementation requirements

Your callback endpoint must:
  1. Verify the request signature — Validate that the callback originates from the AIR Credential platform
  2. Route by schemaId — Direct the callback to the correct business logic based on the credential schema
  3. Return HTTP 2XX — Acknowledge receipt so the platform marks the callback as delivered
  4. Log the event — Record the authorization event for your own audit trail

​
Callback record lifecycle

The platform manages callback records through these states:
StatusCodeMeaning
NOT_SEND-1Initial state — authorization granted but callback not yet dispatched
PENDING0Callback dispatched, awaiting acknowledgment
Delivered—Your endpoint returned HTTP 2XX
The platform retries failed callbacks automatically. Ensure your endpoint is idempotent to handle duplicate deliveries.

​
Best practices

Only include data that verifiers will legitimately need for their compliance process. Minimize the scope of encrypted data to reduce exposure.
The P-256 curve is the default and recommended option. Only switch to secp256k1 if your downstream systems specifically require it.
The callback URL is your real-time notification channel for all CAK authorization events. Downtime means missed notifications, which can delay your audit and risk monitoring.
The platform retries failed callbacks. Your endpoint should handle duplicate deliveries gracefully — use the combination of userId, verifierDid, and schemaId as a deduplication key.