Issuing Credentials

• SDK issuance — the user is present. Your frontend asks your backend for a claimable credentialSubject (via available-vc), then calls air.issueCredential with that subject.
• On-demand issuance — no user interaction with AIR. Your backend resolves the holder, then calls its own issue-vc to build, sign, encrypt, and store the credential.

​

Dashboard setup

• Sandbox: you can complete the issuer setup directly through the Dashboard
• Mainnet: you must generate the required parameters first and then contact us so we can complete the activation and registration on our side.

​

Sandbox Setup

1. Create or use an AIR Dashboard account.
2. Download air-issuer-service and generate a seed. Your signing keys and your Issuer DID are derived from this seed, so keep it secure.
   Do not share the issuer seed with us or expose it in frontend code.
3. Retrieve your Issuer DID:
   Use the provided tooling in air-issuer-service to derive and retrieve your Issuer DID.
4. Open the AIR Dashboard. Navigate to Issuer → Settings
5. Register your issuer by pasting the issuerDID and API key, then click save.
6. Complete the remaining issuer configuration:
   • Supported signature types — BJJ_SIG_2021
   • JWKS URL / key information where applicable
   • Issuer Backend URL and endpoint paths
7. Select or create a schema, then create an issuance program.

​

Mainnet Setup

• Set up air-issuer-service
• Generate and securely store the issuer seed
• Retrieve your Issuer DID
• Generate the required API Key and other configuration parameters
• Prepare your Issuer Backend URL and relevant endpoint configuration

• Issuer DID
• API Key
• Partner ID
• Issuer Backend URL

Important: Sandbox and Mainnet are separate environments. Configuration created in Sandbox should not be assumed to carry over to Mainnet. Mainnet requires its own issuer configuration and activation.

​

Technical integration

​

Configure the backend

• Issuer DID and signing keys
• Schema and program configuration
• API keys / partner auth
• DStorage endpoint configuration
• Issuer data source connection
• A generated private API key (API_KEY) that protects your issuer-hosted endpoints via the x-api-key header

​

Expose available-vc

{
  "holderDID": "did:air:...",
  "pubKey": "0x...",
  "userId": "<partner primary identifier>",
  "schemaId": "<optional schema filter>",
  "proofType": "BJJ_SIG_2021"
}

• Retrieves the user’s eligible credential data from your data source.
• Returns { data: [...] }, with each credential subject encrypted to the holder’s pubKey.
• Accepts optional schemaId and proofType filters.

​

Expose issue-vc

• Retrieves the final user data.
• Builds the VC and signs it with issuer-controlled keys.
• Encrypts the VC to the user’s public key.
• Stores the encrypted VC via DStorage.
• Returns an empty response body after successful issuance. The issuer backend stores the DStorage response in its issuance record.

​

SDK issuance

1. Your frontend asks your issuer backend for a claimable credential.
2. Your backend calls (or runs the logic of) POST /available-vc and returns the credentialSubject to the frontend.
3. The frontend calls air.issueCredential with that credentialSubject, along with the Partner JWT, issuer DID, and program ID.
4. AIR Kit completes the issuance with the logged-in holder. Your backend remains authoritative over the claims it produces.

​

On-demand issuance

• Issuing a KYC credential the moment a user passes identity verification
• Issuing an attendance credential when a venue scan detects a fan’s check-in
• Issuing a subscriber tier credential at the end of each billing cycle
• Issuing a loyalty credential triggered by a purchase event

​

How it works

1. A backend event fires — KYC passed, purchase confirmed, check-in scanned — or your batch job begins.
2. Your backend loads its environment: issuer signing keys and DID, schema and program configuration, Partner auth, and DStorage config.
3. Your backend calls POST /auth/initialize-user with the recipient’s email to resolve or create the user’s AIR Account, receiving the user DID and public key. The email is passed in the request body — not in the Partner JWT.
4. Your backend calls its own POST /issue-vc (or runs the same logic inline) to build the VC, sign it with issuer-controlled keys (BJJ_SIG_2021), encrypt it to the user public key, and store the encrypted envelope via POST /dstorage/vcs.
5. The user presents the credential later at any verifier; no action needed at issuance time.

​

Prerequisites

1. Credential services enabled — Generate your Issuer DID with air-issuer-service and register it with AIR to unlock issuer functionality.
2. Partner ID and Issuer DID — Partner ID from the Developer Dashboard (Accounts → General). Your Issuer DID is derived from your own signing keys; AIR does not generate it for you.
3. Issuance program — A published credential program in the dashboard (Issuer → Programs).
4. JWKS endpoint — A public URL serving your public key for JWT verification. See Partner Authentication.

​

Compliance encryption (CAK)

​

View issued credential records

​

Best practices for issuers

• Only issue credentials after thorough validation of submitted evidence or claims.
• Keep source data and signing keys under issuer control; never expose plaintext user data to AIR.
• Minimize personally identifiable information — issue privacy-preserving credentials whenever possible.
• Adopt open, standardized schemas to maximize compatibility across apps.
• Implement robust expiry and revocation processes, and keep holders and verifiers informed of credential status.
• Treat bulk imports as an operational process for large backfills, not the default integration path.

​

Next steps

• Issuance API Reference
• Verifying Credentials
• Quickstart: Issue Credentials