- Read concepts first: Issuing Credentials
- For JWT/JWKS setup and signing examples, see SDK authentication.
AIR API
AIR API base URLs
The two AIR-hosted endpoints on this page use different hosts:/available-vc, /issue-vc, /admin/*, and the status endpoints are hosted on your issuer service under its public ISSUER_ORIGIN. You never call the AIR API hosts for them.Moca Chain mainnet is live. Production SD-JWT issuers register in the production Developer Dashboard; see Production mainnet access.
Authentication
Direct issuance uses a Partner JWT on both AIR API endpoints. Sign it with the partner’s private key so AIR can verify it through your configured JWKS endpoint, with a headerkid matching the JWKS key. The JWT includes at minimum partnerId.
initialize-user: the Partner JWT also carries the recipient’semailclaim. Send it in the request body aspartnerJwt, with your Partner ID in thex-partner-idheader.dstorage/vcs: send a Partner JWT without anemailclaim in thex-partner-authheader.
initialize-user, and the signing public key when present, are then used to build the credential and store it through /dstorage/vcs.
Your issuer service uses its own keys, described in Your issuer service. They are never sent to the AIR API.
Issuance surfaces
There are two issuance patterns. In both cases, the issuer controls the signing keys and the resulting encrypted credential is stored in DStorage.- Hosted SDK issuance — holder present. Your frontend calls
air.issueCredential(...). AIR resolves the authenticated holder and calls your registered issuer backend’sPOST /available-vcto retrieve an encrypted credential-subject preview. After the holder confirms, AIR callsPOST /issue-vc. The issuer backend generates the authoritative claims, signs the VC, encrypts it to the holder’s public key, persists the issuance record, and uploads the envelope to DStorage. - Direct issuance — no holder interaction. The recipient is resolved by email with
POST /v2/auth/initialize-user, which returns the holder’s DID, encryption public key, and signing public key. The VC is issuer-signed with the signing key in itscnfclaim, encrypted to the encryption key, and stored throughPOST /dstorage/vcs. The SD-JWT issuer service wraps these steps inPOST /admin/issue-vc(see Admin endpoints). You can also call the two AIR API endpoints yourself.
1) Initialize or resolve an AIR account
Resolve or create the recipient’s AIR Account using their email address, and return the AIR user UUID, holder DID, and the holder keys required for direct issuance.Request headers
Request body
Response
Every field can be
null. Do not issue when did or publicKey is missing.
2) Store encrypted VC
Store an encrypted VC envelope in DStorage. Before calling this endpoint, the issuer must build and sign the VC, with the holder’ssigningKey in its cnf claim, then encrypt the complete signed credential to the holder’s publicKey returned by initialize-user.
AIR and DStorage receive the encrypted envelope and do not construct or sign the credential.
Request headers
Request body
Response 201
Your issuer service
These routes run on your own issuer service at its publicISSUER_ORIGIN, not on the AIR API. The examples follow the SD-JWT branch of the AIR issuer service. Iden3 issuers use a separate branch; see Issue Iden3 credentials.
3) Holder-facing endpoints (called by AIR)
Your issuer service exposesPOST /available-vc and POST /issue-vc for hosted SDK issuance. AIR—not the browser—calls these registered endpoints with the holder identity resolved through the authenticated AIR session.
Both endpoints require:
API_KEY in the issuer service and register it with AIR during issuer activation. These routes are hosted under your issuer backend’s public ISSUER_ORIGIN, not under the AIR API base URL.
Do not authorize issuance or retrieve claims from holderDID alone. Use the AIR-resolved partner primary userId to look up the holder’s eligibility and authoritative claims in your own systems. Do not assume this value is interchangeable with the AIR user UUID returned by initialize-user.
POST {ISSUER_ORIGIN}/available-vc
Return credentials the holder can claim. schemaId and proofType are optional filters. AIR calls this endpoint during hosted SDK issuance to discover credentials available to the authenticated holder. The issuer backend validates eligibility using userId, generates authoritative claims, encrypts the preview to pubKey, and returns it to AIR.
schemaId is a credential schema ID—not the Dashboard issuance program ID
Response:
POST {ISSUER_ORIGIN}/issue-vc
AIR calls this endpoint after the holder confirms hosted issuance. The issuer backend regenerates or retrieves the authoritative claims, signs the complete VC, encrypts it to pubKey, persists the issuance record, uploads the encrypted envelope to DStorage, and returns HTTP 201 with an empty body.
On success, the endpoint returns
201 with an empty response body. The issuer backend uploads the encrypted credential and stores the DStorage response internally; callers should not expect a storagePath in this response. A missing or mismatched x-api-key on either issuer-hosted endpoint returns 403, not 401.
4) Admin endpoints (called by your servers)
Admin routes requirex-admin-api-key: <ADMIN_API_KEY>. Call them only from your own servers; never from a browser or through AIR.
POST {ISSUER_ORIGIN}/admin/issue-vc
Resolves the holder through AIR initialize-user, signs the SD-JWT VC with the holder’s signing key as cnf, encrypts it to the holder’s encryption key, and uploads it to DStorage. No registered schema class is needed.
The holder’s
signingKey from initialize-user becomes the credential’s cnf claim, so directly issued credentials are holder-bound like SDK-issued ones.
5) Public endpoints (called by verifiers)
These routes do not require an API key.ISSUER_ORIGIN must be the stable public HTTPS origin of the issuer service, without a trailing slash. For SD-JWT issuers it also defines the issuer DID (did:web:<host>), so changing it changes your issuer identity.
The Iden3 issuer service also serves
GET /credential-status/:nonce, which returns the non-revocation Merkle proof and issuer tree state. See Issue Iden3 credentials.
Example revocation status response:
Error reference
Troubleshooting
- If
dstorage/vcssucceeds, record thestoragePath; the credential is available for the holder to present to any AIR verifier. - If AIR never calls
/available-vcor/issue-vc, confirm that the DID, API key, Available Credentials API, and Issue Credential API are set in Issuer → Settings in the Dashboard for your environment. - For authentication errors, verify the JWT contains
partnerIdand its headerkidmatches your JWKS. Theinitialize-userJWT must also carry the recipient’semailclaim and be sent with the matchingx-partner-idheader. - Ensure your JWKS endpoint is public and
kidmaps to the signing key. - If
dstorage/vcsreturns401 Invalid x-partner-autheven though the token hasscope: "issue",typ: "JWT", and a valid expiry, check the JWKS next. Fetch the exact JWKS URL registered in the Dashboard. Confirm it serves the live public document, not a stale or placeholder copy, and that it contains the token header’skidwith the public key matching your signing key. - The SDK’s
credentialIdis the Dashboard issuance program ID. The issuer backend receivesschemaId. Passing one in place of the other can result in “schema not found” or routing failures.