December 18, 2025 • 5 min read

Blockchain Credential API Integration: A Developer's Guide

Technical guide for developers integrating blockchain credential issuance and verification into applications, including API usage, webhooks, and best practices.

API integration developer technical blockchain

Building with Blockchain Credentials

For developers building applications that issue or verify credentials, API integration enables seamless automation. This technical guide covers blockchain credential API integration patterns, best practices, and implementation considerations.

API Integration Overview

Common Integration Scenarios

Credential Issuance:

LMS course completion → automatic credential issuance
HR system training → employee credentials
Event registration → attendance certificates
Assessment completion → certification issuance

Credential Verification:

Hiring application → credential verification
Vendor onboarding → certification check
Compliance systems → credential status
Access control → qualification verification

Credential Management:

Batch issuance operations
Revocation automation
Expiration monitoring
Analytics retrieval

Architecture Patterns

Direct API Integration:

Your Application → Credential API → Blockchain

Webhook-Driven:

Credential Events → Webhook → Your Application

Hybrid:

Your App → API for issuance
Credential Platform → Webhooks for events

API Authentication

Authentication Methods

API Key Authentication:

Authorization: Bearer YOUR_API_KEY

Best Practices:

Use environment variables for keys
Never commit keys to version control
Rotate keys periodically
Use separate keys for dev/prod

Key Management:

// Good practice
const apiKey = process.env.CREDENTIAL_API_KEY;

// Bad practice - never do this
const apiKey = "sk_live_abc123..."; // Never hardcode!
const apiKey = "abc123..."; // Never hardcode keys!

## Credential Issuance

### Basic Issuance Flow

**1. Prepare Credential Data:**
```javascript
const credentialData = {
  recipientName: "Jane Smith",
  recipientEmail: "[email protected]",
  templateId: "cert_template_123",
  metadata: {
    courseName: "Advanced Project Management",
    completionDate: "2024-12-15",
    grade: "A",
    credits: 3.0
  }
};

2. Issue Credential:

const response = await fetch('https://api.onchaincert.org/v1/credentials', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(credentialData)
});

const credential = await response.json();
console.log('Credential ID:', credential.id);
console.log('Verification URL:', credential.verificationUrl);

3. Handle Response:

// Success response
{
  "id": "cred_abc123",
  "status": "issued",
  "recipientEmail": "[email protected]",
  "verificationUrl": "https://verify.onchaincert.org/cred_abc123",
  "issuedAt": "2024-12-15T10:30:00Z",
  "blockchainTxHash": "0x..."
}

Batch Issuance

For issuing multiple credentials:

const batchData = {
  templateId: "cert_template_123",
  credentials: [
    { recipientName: "Jane Smith", recipientEmail: "[email protected]", metadata: {...} },
    { recipientName: "John Doe", recipientEmail: "[email protected]", metadata: {...} },
    // ... more recipients
  ]
};

const response = await fetch('https://api.onchaincert.org/v1/credentials/batch', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(batchData)
});

Credential Verification

Verification API

Verify by ID:

const verifyResponse = await fetch(
  `https://api.onchaincert.org/v1/credentials/${credentialId}/verify`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);

const verification = await verifyResponse.json();

Verification Response:

{
  "verified": true,
  "credential": {
    "id": "cred_abc123",
    "recipientName": "Jane Smith",
    "issuerName": "Training Academy",
    "credentialType": "Course Completion",
    "issuedAt": "2024-12-15T10:30:00Z",
    "status": "active"
  },
  "blockchain": {
    "network": "polygon",
    "transactionHash": "0x...",
    "blockNumber": 12345678,
    "verifiedAt": "2024-12-15T12:00:00Z"
  }
}

Handling Verification Status

async function verifyCredential(credentialId) {
  const result = await verifyAPI(credentialId);
  
  if (!result.verified) {
    // Handle invalid credential
    console.log('Credential verification failed:', result.reason);
    return { valid: false, reason: result.reason };
  }
  
  if (result.credential.status === 'revoked') {
    // Handle revoked credential
    return { valid: false, reason: 'Credential has been revoked' };
  }
  
  if (result.credential.expiresAt && new Date(result.credential.expiresAt) < new Date()) {
    // Handle expired credential
    return { valid: false, reason: 'Credential has expired' };
  }
  
  return { valid: true, credential: result.credential };
}

Webhook Integration

Setting Up Webhooks

Configure your endpoint to receive credential events:

// Express.js example
app.post('/webhooks/credentials', (req, res) => {
  const event = req.body;
  
  switch (event.type) {
    case 'credential.issued':
      handleCredentialIssued(event.data);
      break;
    case 'credential.claimed':
      handleCredentialClaimed(event.data);
      break;
    case 'credential.verified':
      handleCredentialVerified(event.data);
      break;
    case 'credential.revoked':
      handleCredentialRevoked(event.data);
      break;
  }
  
  res.status(200).send('OK');
});

Webhook Security

Verify webhook signatures:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Error Handling

Common Error Responses

// 400 Bad Request
{ "error": "validation_error", "message": "recipientEmail is required" }

// 401 Unauthorized
{ "error": "unauthorized", "message": "Invalid API key" }

// 404 Not Found
{ "error": "not_found", "message": "Credential not found" }

// 429 Rate Limited
{ "error": "rate_limited", "message": "Too many requests", "retryAfter": 60 }

// 500 Server Error
{ "error": "server_error", "message": "Internal server error" }

Implementing Retry Logic

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        // Rate limited - wait and retry
        await sleep(error.retryAfter * 1000);
        continue;
      }
      if (error.status >= 500 && attempt < maxRetries) {
        // Server error - exponential backoff
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }
      throw error;
    }
  }
}

Best Practices

Security

Never expose API keys in client-side code
Use HTTPS for all API calls
Validate webhook signatures
Implement proper error handling
Log API interactions for debugging

Performance

Use batch operations when possible
Implement caching for verification results
Handle rate limits gracefully
Use async/await for non-blocking operations

Reliability

Implement retry logic
Handle network failures
Monitor API health
Set up alerting for failures

LMS Integration Example

See our complete guide on LMS integration for blockchain credentials.

// Example: Issue credential on course completion
lms.on('courseCompleted', async (event) => {
  const { userId, courseId, completionDate, score } = event;
  
  // Get user details from LMS
  const user = await lms.getUser(userId);
  const course = await lms.getCourse(courseId);
  
  // Issue blockchain credential
  await credentialAPI.issue({
    recipientName: user.fullName,
    recipientEmail: user.email,
    templateId: course.credentialTemplateId,
    metadata: {
      courseName: course.name,
      completionDate: completionDate,
      score: score,
      hoursCompleted: course.hours
    }
  });
});

Getting Started with OnChainCert API

OnChainCert provides comprehensive API access:

API Features:

RESTful API
Webhook support
Batch operations
Comprehensive documentation

Developer Resources:

API documentation
SDKs and libraries
Sandbox environment
Technical support

Ready to integrate blockchain credentials?

Request API access → or view documentation.

Related Articles:

About OnChainCert: We provide developer-friendly APIs for seamless blockchain credential integration.

OnChainCert Team

OnChainCert

Back to Blog