TrustBadge DocsOB 3.0 API
Swagger UI ↗Sign in ↗

Public Documentation · v1

TrustBadge API 연동 가이드

W3C Verifiable Credentials 2.0 · 1EdTech Open Badges 3.0 호환 디지털 자격증서 발급 플랫폼. REST 엔드포인트와 Webhook으로 어떤 외부 시스템과도 연동할 수 있습니다. 본 문서는 로그인 없이 평가용으로 열람 가능합니다.

인터랙티브 API →가입하고 시작하기 ↗

01 · Quick Start

시작하기

가입부터 첫 발급까지 5단계.

01

계정 생성

app.badge.retrust.world 에서 이메일 가입 (무료).

02

KYB 제출

사업자 정보 · 서류 업로드 → 심사 1~3 영업일.

03

API 키 발급

승인 후 Dashboard → API 키 탭에서 [+ 새 키 발급].

04

첫 발급 테스트

아래 Quick Examples 의 cURL / Node.js / Python 참조.

05

Webhook 등록 (선택)

발급 · 폐지 · 만료 이벤트 자동 수신.

Base URL · Auth Header

https://api.badge.retrust.world/apiX-API-Key: tb_xxxxxxxxxxxxxxxxxxxx

02 · Authentication

인증

모든 사설 엔드포인트는 X-API-Key 헤더 필수입니다. 공개 엔드포인트는 인증 없이 호출 가능.

Private

X-API-Key 헤더 필수.
발급 · 폐지 · 캠페인 · Webhook · 분석 등.

Public

인증 없이 호출 가능.
verify, og, share, skills, profiles.

API Key 발급 절차

  • Dashboard → API 키 탭 → [+ 새 키 발급]
  • 키는 한 번만 노출 → 즉시 안전한 저장소(env, AWS Secrets Manager 등)에 저장
  • 키 형식: tb_xxxxxxxxxxxxxxxxxxxx
  • 회수 가능: Dashboard 에서 즉시 무효화

03 · Examples

코드 예시

cURL / Node.js / Python — 가장 자주 쓰는 7가지 시나리오.

A. 기본 배지 발급

curl -X POST https://api.badge.retrust.world/api/v1/assertions \
  -H "X-API-Key: tb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "badgeClassId": "abc123",
    "recipientEmail": "user@example.com",
    "recipientName": "홍길동"
  }'

B. 외부 시스템 연동 발급 (customData + evidence)

예시: 걷기앱이 10K 챌린지 완주자에게 자동 발급.customData는 OB 3.0 의results로 매핑되어 검증 페이지에 자동 노출.

// 1) 배지 클래스 생성 시 dataFields 정의 (한 번만)
await fetch('https://api.badge.retrust.world/api/v1/badges', {
  method: 'POST',
  headers: { 'X-API-Key': key, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: '10K 걷기 골드',
    description: '10,000보 걷기 챌린지 완주',
    frameStyle: 'HEXAGON',
    tier: 'GOLD',
    dataFields: [
      { key: 'steps',    label: '걸음 수',    type: 'number', unit: '보',  required: true },
      { key: 'duration', label: '운동 시간',  type: 'number', unit: '분',  required: true },
      { key: 'distance', label: '거리',       type: 'number', unit: 'km' },
    ],
  }),
});

// 2) 사용자가 챌린지 완주 시 (매 발급마다)
await fetch('https://api.badge.retrust.world/api/v1/assertions', {
  method: 'POST',
  headers: { 'X-API-Key': key, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    badgeClassId: 'badge-10k-gold',
    recipientEmail: user.email,
    customData: {
      steps: 12345,
      duration: 45,
      distance: 8.2,
    },
    evidence: [{
      id: 'https://walking-app.example/records/xyz',
      narrative: '2026-05-16 챌린지 완주 기록',
    }],
  }),
});

C. 배지 검증

공개 — 인증 불필요. 7가지 체크 결과 반환.

curl https://api.badge.retrust.world/api/v1/verify/{assertionId}

응답 구조 (간소화)

{
  "assertionId": "...",
  "valid": true,
  "checks": {
    "found": true,
    "notRevoked": true,
    "notExpired": true,
    "vcStructure": true,
    "proofValid": true,
    "statusListValid": true,
    "blockchainAnchored": true
  },
  "assertion": {
    "badgeName": "...",
    "issuerName": "...",
    "results": [
      { "label": "걸음 수", "value": 12345, "unit": "보" }
    ],
    "evidence": [ ... ]
  }
}

D. 이메일로 수령자 배지 조회

지갑 페이지 / 외부 포털 통합용. 공개 엔드포인트.

curl "https://api.badge.retrust.world/api/v1/verify/wallet/badges?email=user@example.com"

E. 배지 폐지

curl -X POST https://api.badge.retrust.world/api/v1/assertions/{id}/revoke \
  -H "X-API-Key: tb_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "잘못 발급됨"}'

F. CSV 일괄 발급

curl -X POST https://api.badge.retrust.world/api/v1/assertions/csv \
  -H "X-API-Key: tb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "badgeClassId": "abc123",
    "csvContent": "email,name,expiresAt\nuser1@x.com,홍길동,2027-01-01\nuser2@x.com,김철수,"
  }'

G. 캠페인 (예약 일괄 발송)

scheduledAt 생략 시 즉시 발송.

await fetch('https://api.badge.retrust.world/api/v1/campaigns', {
  method: 'POST',
  headers: { 'X-API-Key': key, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: '2026 봄 부트캠프 1기 수료',
    badgeClassId: 'bootcamp-spring-2026',
    recipients: [
      { email: 'alice@x.com', name: '엘리스' },
      { email: 'bob@x.com',   name: '밥' },
    ],
    scheduledAt: '2026-06-15T01:00:00Z', // 즉시 발송 시 생략
  }),
});

04 · Webhooks

Webhook 가이드

이벤트 기반 알림 · HMAC-SHA256 시그니처 검증.

지원 이벤트

assertion.issued배지 발급 완료
assertion.revoked배지 폐지
assertion.expired배지 만료
campaign.completed캠페인 일괄 발송 완료
badge.created배지 클래스 생성

Webhook 등록

await fetch('https://api.badge.retrust.world/api/v1/webhooks', {
  method: 'POST',
  headers: { 'X-API-Key': key, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://your-app.com/webhooks/trustbadge',
    events: ['assertion.issued', 'assertion.revoked'],
    description: '메인 webhook',
  }),
});
// 응답에 secret 포함 — 한 번만 노출됩니다

시그니처 검증

X-TrustBadge-Signature 헤더 = sha256=<hex>. HMAC-SHA256(secret, raw body) 결과와 일치하는지 비교.

import { createHmac } from 'node:crypto';

app.post('/webhooks/trustbadge', (req, res) => {
  const signature = req.headers['x-trustbadge-signature']; // "sha256=..."
  const body = JSON.stringify(req.body);
  const expected = 'sha256=' + createHmac('sha256', WEBHOOK_SECRET)
    .update(body)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('invalid signature');
  }

  const { event, data } = req.body;
  console.log('Event:', event, 'Data:', data);
  res.sendStatus(200);
});

05 · Standards

OB 3.0 호환성

발급되는 모든 VC는 W3C VC 2.0 및 1EdTech Open Badges 3.0 표준을 준수합니다.

다른 OB 3.0 호환 지갑·검증기와 그대로 상호운용 가능하며, JSON-LD 컨텍스트 · 디지털 서명 · 폐지 상태 등 모두 국제 표준에 따라 구성됩니다.

  • DataIntegrityProof · eddsa-jcs-2022 cryptosuite — Ed25519 디지털 서명
  • BitstringStatusList · 효율적인 폐지 / 일시정지 관리
  • DID:web · 발급자 식별 (did:web:did.badge.retrust.world)
  • Evidence · 외부 시스템 기록 참조
  • Results · 측정 가능한 성취 데이터
  • Blockchain Anchor · XDC Network 머클루트 앵커링 — 영구 검증

06 · Rate Limits

율제한

  • 기본 100 요청 / 분 (전역)
  • 429 응답 시 X-RateLimit-Reset 헤더 확인 후 재시도
  • 더 높은 한도가 필요한 경우 biz@retrust.world 로 문의

07 · Errors

오류 코드

모든 오류는 표준 HTTP 상태 코드와 JSON body 로 반환됩니다.

HTTP의미일반적 원인
400Bad Request잘못된 body 형식, 검증 실패
401UnauthorizedAPI 키 없음 / 유효하지 않음
403ForbiddenKYB 미승인, 플랜 한도 초과
404Not Found해당 리소스 없음
422Unprocessable EntitycustomData 검증 실패 등
429Too Many Requests율제한 초과 — X-RateLimit-Reset 확인
500Server Error내부 오류 — biz@retrust.world 문의

응답 본문 형식

{
  "statusCode": 400,
  "message": "validation failed: customData.steps must be a number",
  "error": "Bad Request"
}

08 · Resources

참조 자료

API Docs

Swagger UI (인터랙티브) ↗

API Docs

OpenAPI JSON ↗

Standard

1EdTech OB 3.0 Spec ↗

Standard

W3C VC Data Model 2.0 ↗

Standard

DID:web Method ↗

Dashboard

Sign in ↗

09 · Support

기술 지원

  • 기술 문의: biz@retrust.world
  • 운영 시간: 평일 10:00–18:00 KST
  • 응답 시간: 영업일 기준 24시간 이내
  • 고객센터: 1566-3305

본 문서는 외부 연동 개발자를 위한 공개 가이드입니다. 운영·과금·KYB 등 계정 관련 안내는 Dashboard 내부 문서를 참조하세요.