TrustMe Platform Documentation

Complete developer guide for integrating verifiable credentials and digital trust into your systems

What is TrustMe?

TrustMe is a multi-tenant, blockchain-enabled platform for issuing, managing, and verifying tamper-proof digital credentials and records. It enables organizations to create cryptographically-secured credentials that can be instantly verified without contacting the issuer—transforming how governments, educational institutions, healthcare providers, and enterprises handle trusted documents.

Who is TrustMe for?

Government Agencies

FIRS (Tax Clearance)
VIO (Vehicle Inspection)
NIMC (National Identity)
Licensing & Regulatory Bodies

Educational Institutions

Universities & Polytechnics
Secondary Schools
WAEC, NECO, JAMB
Professional Training Centers

Healthcare Providers

Hospitals & Clinics
Diagnostic Labs
Pharmacies
Health Insurance

Enterprises & Verifiers

Banks & Financial Institutions
HR & Recruitment Firms
Insurance Companies
Foreign Universities

Core Capabilities

Issue & Manage: Create tamper-proof credentials with blockchain anchoring
Verify Instantly: 45ms cached verification without contacting issuer
Audit Trails: Complete compliance with GDPR, HIPAA, SOX support
Multi-Tenant: Namespace isolation for independent organizations
API-First: RESTful APIs with OpenAPI docs, SDKs, and webhooks

New to TrustMe?

Check out the Product Overview for a high-level introduction, or read How It Works to understand the platform flows.

Getting Started

Get up and running with TrustMe in under 10 minutes

Prerequisites

A TrustMe account (sign up at trustme.dev)
API credentials (obtained from Admin Dashboard → API Keys)
Your tenant ID
HTTP client or Node.js 16+ for SDK

Quick Start: Issue Your First Credential

1Obtain API Credentials

Log in to the Admin Dashboard, navigate to API Keys, and click Generate New Key. Copy your API key and tenant ID—you'll need these for authentication.

2Issue a Credential (cURL)

curl -X POST https://api.trustme.dev/v1/credentials \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tax_clearance_template",
    "holderData": {
      "tin": "12345678-0001",
      "fullName": "Micha Abdul",
      "clearancePeriod": "2024",
      "taxStatus": "CLEARED",
      "amountOwed": 0
    }
  }'

3Issue a Credential (TypeScript/Node.js)

import { TrustMeClient } from '@trustme/sdk';

const client = new TrustMeClient({
  apiKey: process.env.TRUSTME_API_KEY,
  tenantId: 'your-tenant-id',
  environment: 'sandbox', // or 'production'
});

// Issue a credential
const credential = await client.credentials.create({
  templateId: 'tax_clearance_template',
  holderData: {
    tin: '12345678-0001',
    fullName: 'Micha Abdul',
    clearancePeriod: '2024',
    taxStatus: 'CLEARED',
    amountOwed: 0,
  },
});

console.log('Credential issued:', credential.id);
console.log('QR Code:', credential.qrCodeUrl);

// Verify a credential
const verification = await client.credentials.verify(credential.id);

console.log('Status:', verification.status); // ACTIVE
console.log('Verified in:', verification.verificationTime); // ~45ms

4Verify the Credential

Use the verification endpoint to check credential authenticity:

curl https://api.trustme.dev/v1/verify/cred_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Sandbox Environment

Use sandbox.trustme.dev for testing without affecting production data. All credentials issued in sandbox are marked as test credentials.

Next Steps

Learn Core Concepts

Understand tenants, credentials, schemas, and the credential lifecycle.

Explore API Reference

Detailed documentation of all REST endpoints, payloads, and responses.

Core Concepts

Understanding the building blocks of TrustMe Platform

Tenants & Organizations

A tenant represents an independent organization on the TrustMe platform. Each tenant has:

Dedicated namespace: Isolated blockchain contracts and data
Custom branding: Logo, colors, and theming
Independent users: Admins, issuers, verifiers with role-based permissions
Separate quota & billing: Usage tracking per tenant

Examples: tenant_firs, tenant_abu (Ahmadu Bello University), tenant_luth (Lagos University Teaching Hospital)

Credentials & Documents

A credential (or document) is a verifiable digital record issued by a tenant. Credentials have:

Credential Properties

Identity

• Unique ID (e.g., cred_abc123)
• Cryptographic hash (SHA-256)
• Digital signature (ECDSA)
• Blockchain anchor (transaction hash)

Metadata

• Template/Schema reference
• Issuer (tenant + user)
• Holder (subject)
• Issue & expiry dates

Status

• DRAFT → ACTIVE → VERIFIED
• REVOKED, SUSPENDED
• Status history with timestamps

Sharing

• QR code for scanning
• Shareable URL
• PDF export
• API access

Credential Templates (Schemas)

Templates define the structure of credentials using JSON Schema. Examples:

• Tax Clearance: TIN, taxpayer name, period, status, amount owed
• Degree Certificate: Student name, program, CGPA, graduation date, classification
• Medical Report: Patient ID, diagnosis, test results, doctor, hospital
• Vehicle Inspection: VIN, owner, inspection date, roadworthiness status

Actors & Roles

TrustMe supports 19 predefined roles with granular permissions:

Issuer Roles

admin

Full platform access

platform_admin

Platform-level operations

issuer_admin

Tenant document/template management

issuer

Create and issue credentials

Verifier & Audit Roles

verifier_admin

Manage verification settings

verifier

Verify credentials

auditor

Access audit logs & reports

viewer

Read-only access

Credential Lifecycle

Credentials move through these stages:

DRAFT

Created but not yet issued

ACTIVE

Issued and blockchain-anchored

ISSUED

Delivered to holder

VERIFIED

Successfully verified by third party

REVOKED

Permanently invalidated

SUSPENDED

Temporarily paused

EXPIRED

Past expiration date

Authentication & Security

How to securely authenticate with TrustMe APIs

Authentication Methods

TrustMe supports multiple authentication mechanisms:

API Keys

Long-lived tokens for server-to-server integration

• Scoped permissions
• Rate limiting per key
• Usage tracking
• Rotation support

JWT Tokens

Short-lived session tokens for user authentication

• 15-minute access tokens
• 7-day refresh tokens
• Automatic rotation
• MFA support (TOTP)

Making Authenticated Requests

All API requests require two headers:

Authorization: Bearer YOUR_API_KEY - Your API key or JWT token
X-Tenant-ID: your-tenant-id - Your tenant identifier

Example (cURL)

# Using API Key
curl https://api.trustme.dev/v1/credentials \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: your-tenant-id"

# Response includes JWT for session
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 900
}

Example (TypeScript SDK)

import { TrustMeClient } from '@trustme/sdk';

const client = new TrustMeClient({
  apiKey: process.env.TRUSTME_API_KEY,
  tenantId: process.env.TRUSTME_TENANT_ID,
  environment: 'production',
});

// SDK handles token refresh automatically
const credentials = await client.credentials.list();

Security Best Practices

• Never commit API keys to version control
• Use environment variables for credentials
• Rotate API keys every 90 days
• Use HTTPS only (all HTTP requests are rejected)
• Apply least-privilege permissions to API keys
• Monitor API key usage in Admin Dashboard

OAuth & OIDC Integration

For delegated access, TrustMe supports OAuth 2.0 and OpenID Connect:

Authorization Endpoint: https://auth.trustme.dev/oauth/authorize
Token Endpoint: https://auth.trustme.dev/oauth/token
Supported Grants: Authorization Code, Client Credentials

For detailed OAuth integration, see our Advanced Topics section or contact support@trustme.dev.

REST API Reference

Complete API documentation for all TrustMe endpoints

API Base URLs

Production:

https://api.trustme.dev/v1

Sandbox:

https://sandbox.trustme.dev/v1

Credentials API

POST/v1/credentialsIssue a new credential

POST https://api.trustme.dev/v1/credentials

{
  "templateId": "tax_clearance_template",
  "holderData": {
    "tin": "12345678-0001",
    "fullName": "Micha Abdul",
    "clearancePeriod": "2024",
    "taxStatus": "CLEARED"
  },
  "expiresAt": "2025-12-31T23:59:59Z",
  "metadata": {
    "issuingOffice": "FIRS Lagos"
  }
}

Response (201 Created):
{
  "id": "cred_abc123",
  "status": "ACTIVE",
  "documentHash": "0x8f2a9b...",
  "blockchainAnchor": {
    "transactionHash": "0xabc...",
    "blockNumber": 12345678
  },
  "qrCodeUrl": "https://verify.trustme.dev/qr/cred_abc123",
  "shareableUrl": "https://trustme.dev/verify/cred_abc123",
  "issuedAt": "2024-11-17T10:30:00Z"
}

GET/v1/credentials/:idGet credential details

Returns complete credential information including blockchain proof and status history.

GET/v1/credentialsList credentials

Query parameters: status, templateId, issuedAfter, page, perPage

Verification API

GET/v1/verify/:documentIdVerify credential authenticity

GET https://api.trustme.dev/v1/verify/cred_abc123

Response (200 OK):
{
  "id": "cred_abc123",
  "status": "ACTIVE",
  "isValid": true,
  "issuer": {
    "tenantId": "tenant_firs",
    "name": "Federal Inland Revenue Service"
  },
  "holder": {
    "tin": "12345678-0001",
    "fullName": "Micha Abdul"
  },
  "issuedAt": "2024-11-17T10:30:00Z",
  "expiresAt": "2025-12-31T23:59:59Z",
  "blockchainProof": {
    "transactionHash": "0xabc...",
    "verified": true
  },
  "verificationTime": "45ms",
  "verifiedAt": "2024-11-17T15:22:10Z"
}

Performance: Cached verifications return in ~45ms. Cold verifications take ~1.2s.

Status & Revocation API

POST/v1/credentials/:id/revokeRevoke a credential

POST https://api.trustme.dev/v1/credentials/cred_abc123/revoke

{
  "reason": "FRAUD_DETECTED",
  "comments": "Credential holder reported identity theft",
  "effectiveDate": "2024-11-17T16:00:00Z"
}

Response (200 OK):
{
  "id": "cred_abc123",
  "status": "REVOKED",
  "revokedAt": "2024-11-17T16:00:00Z",
  "revokedBy": "user_123",
  "revocationReason": "FRAUD_DETECTED",
  "blockchainUpdate": {
    "transactionHash": "0xdef...",
    "confirmedAt": "2024-11-17T16:00:15Z"
  }
}

Revocation Reasons:

• FRAUD_DETECTED

• SUPERSEDED

• DATA_BREACH

• AFFILIATION_TERMINATED

• PRIVILEGE_WITHDRAWN

• ERROR_IN_ISSUANCE

POST/v1/credentials/:id/suspendTemporarily suspend credential

Suspend a credential temporarily (can be reactivated later). Useful for pending investigations.

Audit Logs API

GET/v1/audit-logsQuery audit trail

GET https://api.trustme.dev/v1/audit-logs?resourceId=cred_abc123

Response (200 OK):
{
  "logs": [
    {
      "id": "log_001",
      "timestamp": "2024-11-17T10:30:00Z",
      "action": "CREDENTIAL_ISSUED",
      "actor": "user_123",
      "resourceType": "CREDENTIAL",
      "resourceId": "cred_abc123",
      "ipAddress": "192.168.1.1",
      "userAgent": "TrustMe SDK/1.0",
      "result": "SUCCESS"
    },
    {
      "id": "log_002",
      "timestamp": "2024-11-17T15:22:10Z",
      "action": "CREDENTIAL_VERIFIED",
      "actor": "verifier_456",
      "resourceType": "CREDENTIAL",
      "resourceId": "cred_abc123",
      "ipAddress": "203.0.113.1",
      "result": "SUCCESS",
      "metadata": {
        "verificationTime": "45ms"
      }
    }
  ],
  "pagination": {
    "total": 2,
    "page": 1,
    "perPage": 50
  }
}

Query Parameters:

• resourceId - Filter by credential ID
• resourceType - CREDENTIAL, USER, TENANT
• action - ISSUED, VERIFIED, REVOKED, etc.
• actor - Filter by user ID
• startDate / endDate - Date range

Common Error Codes

Code	Meaning	Resolution
`401`	Unauthorized	Check API key and X-Tenant-ID header
`403`	Forbidden	Insufficient permissions for this action
`404`	Not Found	Credential or resource doesn't exist
`422`	Validation Error	Check request payload against schema
`429`	Rate Limited	Wait or upgrade quota limit
`500`	Server Error	Contact support with error ID

Webhooks & Events

Real-time notifications for credential lifecycle events

Event Types

TrustMe publishes events via webhooks and RabbitMQ for real-time integration:

Credential Events

• credential.issued - New credential created

• credential.verified - Credential verified

• credential.revoked - Credential revoked

• credential.suspended - Credential suspended

• credential.expired - Credential expired

System Events

• user.created - New user added

• user.role_changed - Role modified

• template.created - New template

• audit.export - Audit report generated

Webhook Payload Example

{
  "event": "credential.issued",
  "timestamp": "2024-11-17T10:30:00Z",
  "data": {
    "credentialId": "cred_abc123",
    "tenantId": "tenant_firs",
    "status": "ACTIVE",
    "holderData": {
      "tin": "12345678-0001",
      "fullName": "Micha Abdul"
    },
    "issuedBy": "user_123",
    "blockchainAnchor": {
      "transactionHash": "0xabc...",
      "blockNumber": 12345678
    }
  },
  "signature": "sha256=abc123..."
}

Handling Webhooks

Configure webhook URLs in the Admin Dashboard. TrustMe will POST events to your endpoint with a signature for verification.

import crypto from 'crypto';

export async function POST(request: Request) {
  const payload = await request.text();
  const signature = request.headers.get('X-TrustMe-Signature');

  // Verify webhook signature
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  if (signature !== `sha256=${expectedSignature}`) {
    return new Response('Invalid signature', { status: 401 });
  }

  const event = JSON.parse(payload);

  // Handle different event types
  switch (event.event) {
    case 'credential.issued':
      await handleCredentialIssued(event.data);
      break;
    case 'credential.verified':
      await handleCredentialVerified(event.data);
      break;
    case 'credential.revoked':
      await handleCredentialRevoked(event.data);
      break;
  }

  return new Response('OK', { status: 200 });
}

Webhook Security

• Always verify the X-TrustMe-Signature header
• Use HTTPS endpoints only
• Respond with 200 OK quickly (< 5s)
• Process events asynchronously if needed
• Implement idempotency (events may be delivered multiple times)

TrustMe retries failed webhook deliveries with exponential backoff (3 attempts over 24 hours). Check webhook delivery logs in the Admin Dashboard under Settings → Webhooks.

Sector-Specific Integration Guides

Real-world examples for different industries and use cases

FIRS / Tax Authority

Issue digital tax clearance certificates that banks and partners can verify instantly.

Use Case

When a taxpayer needs tax clearance for a bank loan, FIRS issues a verifiable certificate. The bank scans the QR code or uses the API to verify authenticity instantly—no phone calls or emails needed.

Improvement

Verification time: 2-4 weeks → under 1 second

Fraud reduction: ~95% (eliminates fake certificates)

Implementation

// FIRS: Issue Tax Clearance Certificate
const taxClearance = await client.credentials.create({
  templateId: 'tax_clearance_template',
  holderData: {
    tin: '12345678-0001',
    fullName: 'ABC Limited',
    businessName: 'ABC Trading Company',
    clearancePeriod: '2024',
    taxStatus: 'CLEARED',
    amountOwed: 0,
    taxesPaid: 5000000, // NGN
    clearanceType: 'STANDARD',
    validUntil: '2025-12-31'
  },
  expiresAt: '2025-12-31T23:59:59Z',
  metadata: {
    issuingOffice: 'FIRS Lagos',
    clearanceNumber: 'CLR/2024/001234'
  }
});

console.log('Tax Clearance:', taxClearance.shareableUrl);
// Bank can now verify via: GET /v1/verify/${taxClearance.id}

VIO / Vehicle Inspection

Digital roadworthiness certificates with QR codes for instant on-the-spot verification.

Mobile-First: VIO inspectors use tablet/mobile apps to issue certificates on-site. Vehicle owners receive QR codes via SMS. Enforcement officers verify roadworthiness by scanning QR codes.

NIMC / National Identity

Create a verified identity backbone for KYC across banking, telecom, and government services.

Privacy First: NIMC integration supports data minimization and consent management. Only verified identity attributes (e.g., "over 18", "Nigerian citizen") are shared, not full PII.

Universities & Schools

Digital degrees, transcripts, and result slips with instant employer verification.

Batch Issuance Example

// University: Issue Degree Certificate
const degreeCert = await client.credentials.create({
  templateId: 'degree_certificate_template',
  holderData: {
    studentId: 'ABU/CSC/2020/12345',
    fullName: 'Jane Smith',
    program: 'B.Sc. Computer Science',
    faculty: 'Faculty of Science',
    department: 'Computer Science',
    graduationDate: '2024-07-15',
    cgpa: 4.75,
    classification: 'First Class Honours',
    certificateNumber: 'ABU/2024/001234'
  },
  metadata: {
    university: 'Ahmadu Bello University',
    convocationYear: '2024'
  }
});

// Employer verification
const verification = await client.credentials.verify(degreeCert.id);
console.log('Degree verified:', verification.isValid);

Batch Processing: Universities can upload CSV files with hundreds or thousands of graduating students. TrustMe processes batch issuance and generates individual QR codes for each certificate.

Hospitals & Labs

HIPAA-compliant medical records and lab results with patient-controlled sharing.

// Hospital: Issue Lab Results
const labResult = await client.credentials.create({
  templateId: 'lab_result_template',
  holderData: {
    patientId: 'LUTH/2024/56789',
    patientName: 'Micha Abdul', // (encrypted in storage)
    testType: 'Complete Blood Count',
    testDate: '2024-11-15',
    results: {
      wbc: '7.5',
      rbc: '5.2',
      hemoglobin: '14.5',
      platelets: '250'
    },
    reference: 'LAB/2024/001234',
    signingDoctor: 'Dr. Smith',
    laboratory: 'LUTH Central Lab'
  },
  consentRequired: true, // Holder must approve sharing
  metadata: {
    hospital: 'Lagos University Teaching Hospital',
    department: 'Pathology'
  }
});

// Patient shares with consent
const shareToken = await client.credentials.createShareToken(labResult.id, {
  validFor: '7days',
  allowedVerifiers: ['insurance_company_id']
});

HIPAA Compliance

Medical records are encrypted at rest and in transit. Patient consent is required before sharing. All access is logged with 22-field audit trails for compliance reporting.

Advanced Topics

Deep dives into multi-tenancy, performance, and advanced features

Multi-Tenant Architecture

TrustMe provides complete tenant isolation at multiple levels:

Namespace Isolation: Separate blockchain contracts per tenant via Hyperledger FireFly
Database RLS: Row-Level Security ensures data partitioning in PostgreSQL
Independent Configuration: Each tenant has custom branding, quotas, and settings
Billing Separation: Usage tracking and billing per tenant

Performance & Rate Limits

Default Rate Limits

Credential Issuance:1,000/hour per tenant

Verification:10,000/hour per API key

API Requests:1,000/minute per tenant

Batch Upload:5,000 credentials/batch

Environments

Sandbox

Testing environment with:

• Test blockchain (no real transactions)
• Sample data and templates
• Reduced rate limits
• Free tier available

Production

Live environment with:

• Ethereum/Polygon mainnet
• Real blockchain fees
• 99.9% uptime SLA
• Full audit compliance

Schema Versioning

Credential templates support versioning for backward compatibility:

Templates use semantic versioning (e.g., tax_clearance_v1.2.0)
Old credentials remain valid even after template updates
Breaking changes require new template versions
API accepts both template ID and version number

FAQ & Support

Common questions and how to get help

How do I get started with TrustMe?

Sign up for an account, create your tenant, generate API keys from the Admin Dashboard, and follow the Getting Started guide above.

What authentication method should I use?

For server-to-server integration, use API keys. For user-facing applications, use JWT tokens with OAuth/OIDC.

How long does blockchain anchoring take?

Blockchain confirmation typically takes 15-30 seconds on Ethereum. The credential is immediately usable after issuance (status: ACTIVE).

Can I revoke a credential?

Yes. Use the /v1/credentials/:id/revoke endpoint. Revocation is immediate and propagates to all verifiers within seconds via cache invalidation.

What happens if a verification fails?

The API returns a 200 response with isValid: false and details about why (revoked, expired, not found, or tampered).

How do I handle production blockchain fees?

Blockchain fees are included in your subscription plan up to your transaction quota. Additional transactions are billed at cost (typically $0.01-0.05 per anchor).

Is TrustMe GDPR/HIPAA compliant?

Yes. TrustMe provides data minimization, consent management, audit trails, and exportable compliance reports for GDPR, HIPAA, and SOX.

Can I use my own blockchain network?

Enterprise customers can deploy to private Ethereum/Besu networks. Contact sales@trustme.dev for custom deployment options.

Need More Help?

Our developer support team is here to help with integration questions, troubleshooting, and best practices.

Email Support Contact Sales System Status