Skip to main content
This page covers two separate surfaces. Do not mix their base URLs or authentication headers.

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 header kid matching the JWKS key. The JWT includes at minimum partnerId.
  • initialize-user: the Partner JWT also carries the recipient’s email claim. Send it in the request body as partnerJwt, with your Partner ID in the x-partner-id header.
  • dstorage/vcs: send a Partner JWT without an email claim in the x-partner-auth header.
The DID and encryption public key returned by 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’s POST /available-vc to retrieve an encrypted credential-subject preview. After the holder confirms, AIR calls POST /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 its cnf claim, encrypted to the encryption key, and stored through POST /dstorage/vcs. The SD-JWT issuer service wraps these steps in POST /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’s signingKey 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 public ISSUER_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 exposes POST /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:
Configure the same key as 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 require x-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/vcs succeeds, record the storagePath; the credential is available for the holder to present to any AIR verifier.
  • If AIR never calls /available-vc or /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 partnerId and its header kid matches your JWKS. The initialize-user JWT must also carry the recipient’s email claim and be sent with the matching x-partner-id header.
  • Ensure your JWKS endpoint is public and kid maps to the signing key.
  • If dstorage/vcs returns 401 Invalid x-partner-auth even though the token has scope: "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’s kid with the public key matching your signing key.
  • The SDK’s credentialId is the Dashboard issuance program ID. The issuer backend receives schemaId. Passing one in place of the other can result in “schema not found” or routing failures.