Issue Credentials on Behalf (Private Beta)

Server-to-server API for issuing credentials programmatically from your backend without user interaction. Ideal for bulk issuance and automated workflows.

Key Features:

• Automatic user creation if the user doesn't exist
• Asynchronous issuance with status tracking
• Control over duplicate credential handling

When to use: Backend automation, bulk operations. For interactive user flows, use the SDK method.

Prerequisites

Before using the Issue on Behalf API, ensure you have:

1. Feature Activation - Contact support to enable Issue on Behalf for your partner account
2. Partner ID and Issuer DID - Obtain from the Developer Dashboard (Accounts → General)
3. Issuance Program - Create and publish an issuance program (Issuer → Programs)
4. Partner JWT Setup - Configure your JWKS endpoint and private key for signing. See Partner Authentication
5. User Email - The email address of the user receiving the credential

Feature Activation Required

The Issue on Behalf feature must be activated for your partner account. Contact support to request access.

API Authentication

All requests require a Partner JWT passed via the x-partner-auth header. The JWT must include:

• partnerId: Your Partner ID
• email: The user's email address
• scope: Must be set to "issue"
• exp: Expiration timestamp (recommended: 5 minutes)

Example JWT Payload:

{
  "partnerId": "your-partner-id",
  "email": "user@example.com",
  "scope": "issue",
  "exp": 1737281925,
  "iat": 1737281625
}

See Partner Authentication for detailed JWT generation examples.

API Endpoints

1. Issue Credential

Initiates the credential issuance process for a user. If the user doesn't exist, they will be automatically created.

Endpoint:

POST https://api.sandbox.mocachain.org/v1/credentials/issue-on-behalf

Headers:

x-partner-auth: {your-partner-jwt}
Content-Type: application/json

Request Body:

{
  "issuerDid": "did:air:id:test:...",
  "credentialId": "c21s70g0i54sn0023172Cv",
  "credentialSubject": {
    "age": 25,
    "location": "United States",
    "isMember": true
  },
  "onDuplicate": "revoke"
}

Parameters:

Field	Type	Required	Description
issuerDid	string	Yes	Your Issuer DID from the Developer Dashboard
credentialId	string	Yes	The Issuance Program ID
credentialSubject	object	Yes	Credential data matching your schema
onDuplicate	string	No	Behavior for duplicate credentials: "ignore" (return existing) or "revoke" (revoke and re-issue). Default: "revoke"

Response:

{
  "coreClaimHash": "239704895d0c4693d33ee7ab9e37c6eb295f178d80074a32d4ace53b1a779c44",
  "credentialId": "c21s70g0i54sn0023172Cv",
  "userUuid": "7f01c42c-02cf-4325-96ed-ba034700f724"
}

Response Fields:

Field	Type	Description
coreClaimHash	string	Unique hash identifier for the credential. Use this to check issuance status
credentialId	string	The Issuance Program ID (echoed from request)
userUuid	string	The UUID of the user who received the credential

Important Notes

Asynchronous Processing: The credential is submitted for issuance but may not be fully written to the blockchain when this endpoint returns. Use the Status API to check completion.

User Consent: Users must consent to partners issuing credentials on their behalf. If a user rejects consent, the API will throw an error. For newly created users, they will be prompted on first login whether to keep or remove all issued credentials.

2. Check Issuance Status

Query the status of a credential issuance using the coreClaimHash returned from the issue endpoint.

Endpoint:

GET https://api.sandbox.mocachain.org/v1/credentials/status?coreClaimHash={hash}

Headers:

x-partner-auth: {your-partner-jwt}

Query Parameters:

Parameter	Type	Required	Description
coreClaimHash	string	Yes	The hash returned from the issue endpoint

Response:

{
  "coreClaimHash": "239704895d0c4693d33ee7ab9e37c6eb295f178d80074a32d4ace53b1a779c44",
  "expirationDate": "2031-01-18 07:18:40",
  "expirationTick": 1926487120,
  "issuanceDate": "2026-01-19 07:18:45",
  "issuerDid": "did:air:id:test:5P44fsVUhPctDTWH2Nz26pZJFsg6CqyiAELTGeVQDB",
  "issuerId": "c21mu070xonbs0035989to",
  "publicKey": null,
  "schemeId": "c21pa061mq2m30012055K7",
  "vcDstorageId": "c28t305048pgb02t5286t4",
  "vcId": "c28t30c048pe502a3713w0",
  "vcStatus": "ONCHAIN"
}

vcStatus Values:

Status	Description
WAIT_ONCHAIN	Credential is being processed and waiting to be written to the blockchain
ONCHAIN	Credential is successfully written to the blockchain

Best Practices

• User Consent: Existing users must have consented to credential issuance beforehand. Newly created users will be prompted on first login to accept or reject all issued credentials.
• Duplicate Handling: Use onDuplicate: "ignore" for idempotent operations, "revoke" (default) when credential data has changed.
• JWT Scope: Always include "scope": "issue" in your JWT payload.

Environment URLs

Environment	Base URL
Sandbox	https://api.sandbox.mocachain.org/v1
Production	https://api.mocachain.org/v1

Related Documentation

• Partner Authentication - JWT generation and JWKS setup
• Schema Creation - Create credential schemas
• Credential Verification - Verify issued credentials