User Guide — Issuers

Issuance Flow

View as Markdown

Credential issuance is the process by which an Issuer creates, signs, and delivers a Verifiable Credential to a Holder.

Issuance Flow Overview

Step-by-Step

Step 1: Issuer Submits Issuance Request

1POST /api/v1/credentials/issue
2Content-Type: application/json
3Authorization: Bearer <issuer-api-key>
4
5{
6  "schemaId": "did:adi:schema:university-degree-v1",
7  "issuerDid": "did:adi:issuer001...",
8  "holderDid": "did:adi:holder001...",
9  "claims": {
10    "degree": {
11      "type": "BachelorDegree",
12      "name": "Bachelor of Science in Computer Science",
13      "university": "MIT",
14      "graduationYear": 2025,
15      "gpa": 3.8
16    }
17  },
18  "expirationDate": "2030-12-31T23:59:59Z",
19  "proofType": "Ed25519Signature2020",
20  "revocable": true
21}

Steps 2-3: Verification

The API verifies:

  • Issuer DID exists and is not deactivated
  • Issuer has an assertionMethod key of the requested proof type
  • Schema exists in the Schema Registry
  • Issuer is authorized to issue against this schema (if restricted)

Step 4: Schema Validation

The claims object is validated against the schema’s JSON Schema definition. All required fields must be present and types must match.

Steps 5-6: VC Construction and Signing

The API constructs the full VC document with:

  • JSON-LD @context from the schema
  • type array from schema + VerifiableCredential
  • credentialStatus entry for revocation tracking
  • proof object signed with the issuer’s private key

Step 7: Status Registration

A status entry is created in the Revocation Registry for future revocation capability.

Step 8: Response

1{
2  "credential": {
3    "@context": ["https://www.w3.org/2018/credentials/v1", "..."],
4    "id": "urn:uuid:f47ac10b-58cc-4372-a567-0e02b2c3d479",
5    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
6    "issuer": { "id": "did:adi:issuer001...", "name": "MIT" },
7    "issuanceDate": "2026-03-28T10:00:00Z",
8    "expirationDate": "2030-12-31T23:59:59Z",
9    "credentialSubject": {
10      "id": "did:adi:holder001...",
11      "degree": { "..." }
12    },
13    "credentialStatus": { "..." },
14    "proof": { "..." }
15  },
16  "credentialId": "urn:uuid:f47ac10b-58cc-4372-a567-0e02b2c3d479",
17  "statusListIndex": 3
18}

Steps 9-11: Credential Delivery

The issuer delivers the VC to the holder via:

  1. DIDComm: Encrypted message to the holder’s agent endpoint
  2. QR Code: Holder scans a QR code containing the credential offer
  3. API: Holder retrieves the credential via API using a one-time token

DIDComm Credential Offer

1{
2  "type": "https://didcomm.org/issue-credential/3.0/offer-credential",
3  "id": "offer-001",
4  "from": "did:adi:issuer001...",
5  "to": ["did:adi:holder001..."],
6  "body": {
7    "credential_preview": {
8      "type": "UniversityDegreeCredential",
9      "attributes": [
10        { "name": "degree.type", "value": "BachelorDegree" },
11        { "name": "degree.university", "value": "MIT" }
12      ]
13    },
14    "formats": [
15      {
16        "attach_id": "vc-1",
17        "format": "aries/ld-proof-vc-detail@v1.0"
18      }
19    ]
20  }
21}

Bulk Issuance

Issue credentials to multiple holders in a single API call:

1POST /api/v1/credentials/issue/batch
2Content-Type: application/json
3Authorization: Bearer <issuer-api-key>
4
5{
6  "schemaId": "did:adi:schema:university-degree-v1",
7  "issuerDid": "did:adi:issuer001...",
8  "credentials": [
9    {
10      "holderDid": "did:adi:holder001...",
11      "claims": { "degree": { "type": "BachelorDegree", "..." } }
12    },
13    {
14      "holderDid": "did:adi:holder002...",
15      "claims": { "degree": { "type": "MasterDegree", "..." } }
16    }
17  ],
18  "expirationDate": "2030-12-31T23:59:59Z"
19}

Response:

1{
2  "results": [
3    { "holderDid": "did:adi:holder001...", "credentialId": "urn:uuid:...", "status": "issued" },
4    { "holderDid": "did:adi:holder002...", "credentialId": "urn:uuid:...", "status": "issued" }
5  ],
6  "issued": 2,
7  "failed": 0,
8  "transactionHash": "0xbatch..."
9}

BBS+ Issuance

For credentials that support selective disclosure, use the BBS+ proof type:

1POST /api/v1/credentials/issue
2Content-Type: application/json
3
4{
5  "schemaId": "did:adi:schema:university-degree-v1",
6  "issuerDid": "did:adi:issuer001...",
7  "holderDid": "did:adi:holder001...",
8  "claims": { "..." },
9  "proofType": "BbsBlsSignature2020"
10}

The resulting VC will have a BbsBlsSignature2020 proof that enables the holder to create derived proofs revealing only selected attributes.

Agent Delegation Issuance

Issuing a delegation credential to an AI agent follows the same flow but uses the agent delegation schema:

1POST /api/v1/credentials/issue
2Content-Type: application/json
3
4{
5  "schemaId": "did:adi:schema:agent-delegation-v1",
6  "issuerDid": "did:adi:human001...",
7  "holderDid": "did:adi:agent:7f3a...",
8  "claims": {
9    "delegator": "did:adi:human001...",
10    "delegate": "did:adi:agent:7f3a...",
11    "scope": ["purchase-groceries", "compare-prices"],
12    "constraints": {
13      "maxSpendPerWeek": 200,
14      "authorizedMerchants": ["FreshMart", "OrganicCo"]
15    },
16    "maxDepth": 1
17  },
18  "expirationDate": "2026-09-15T00:00:00Z"
19}

Issuance Errors

Error CodeDescription
ISSUER_NOT_FOUNDIssuer DID does not exist
ISSUER_DEACTIVATEDIssuer DID has been deactivated
SCHEMA_NOT_FOUNDSchema ID not in registry
SCHEMA_VALIDATION_FAILEDClaims do not match schema
HOLDER_NOT_FOUNDHolder DID does not exist
SIGNING_FAILEDFailed to sign the credential
RATE_LIMIT_EXCEEDEDToo many issuance requests