Skip to main content
Direct Issuance lets your backend job or a controlled script issue a credential straight to a user’s AIR Account without hosting a live issuer backend and without any action from the user at issuance time. The user doesn’t need to be in a session, open a wallet, or interact with any UI. The issuer holds its own keys and data throughout, signing and encrypting each credential before it reaches AIR. This enables zero-friction, invisible credential issuance for use cases like:
  • 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
The user simply benefits from the credential next time they interact with a verifier.
Direct issuance vs hosted Issuer BackendUse direct issuance when you don’t want to run a live backend. If you need queryable available credentials and on-demand issuance triggered through the SDK, use the hosted Issuer Backend instead. Both paths sign with issuer-controlled keys and store an encrypted envelope in DStorage.
Direct issuance is not a single turnkey API call. You run it through the air-issuer-service tool — either as a job that reads a CSV of recipients, or as your own script replicating the same logic. Under the hood it calls the AIR issuance endpoints (initialize-user, then dstorage/vcs); see the Issuance API Reference.
The bundled CSV runner uses initialize-user compatibility contract (x-partner-id, { partnerJwt }, and the recipient email inside the JWT). Do not copy that bootstrap request into a new integration. Custom jobs should use the current v1 contract documented below: send a Partner JWT with scope: "issue" in x-partner-auth, and put the recipient email in the request body.

​
How it works

Custom jobs using the current v1 API follow this flow. The bundled CSV runner performs the same issuance steps but uses the legacy v2 bootstrap request described above.
  1. A backend event fires — KYC passed, purchase confirmed, check-in scanned — or your custom batch begins.
  2. Your job loads its environment: issuer signing keys and DID, schema and program configuration, Partner auth, DStorage config, and source data access.
  3. Your job calls 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 here in the request body — not in the Partner JWT.
  4. Your job retrieves the user’s source data.
  5. Your job builds the VC, signs it with issuer-controlled keys (BJJ_SIG_2021), and encrypts it to the returned user public key.
  6. Your job stores the encrypted VC envelope via dstorage/vcs and records the returned storagePath.
  7. The user presents the credential later at any verifier; no action needed at issuance time.
The issuer holds the data and keys throughout; AIR stores only the encrypted envelope and metadata.

​
Prerequisites

Before running direct issuance you need:
  1. Credential services enabled — Generate your Issuer DID with air-issuer-service and register it with AIR to unlock issuer functionality. See the activation flow in Issuing Credentials.
  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.

​
Auth for custom v1 jobs

Custom v1 direct issuance authenticates via a Partner JWT attached to each request, signed with scope: "issue". The JWT does not carry an email claim — the recipient is identified when you call initialize-user. For setup, key generation, and examples see Partner Authentication.

​
Recipient email for custom v1 jobs

For the v1 contract, the recipient’s email is the routing key that determines which AIR Account the credential lands in. Supply it in the initialize-user request body, not the JWT. Because it is the routing key:
  • Resolve the recipient’s email from the triggering event or CSV row; never hardcode a shared value.
  • Never reuse a partner, service, or admin email as a recipient.
  • Dedupe by recipient email + program ID before issuing, so an event replay or loop can’t fan out to the wrong account.

​
Next Steps