OpenBadge API
Digital credentials and micro-credentials
Overview
The OpenBadge API lets you issue and verify digital credentials for skills, achievements, and learning outcomes.
Badges are portable, verifiable, and data-rich; students can share them across platforms.
Use OpenBadge to recognize accomplishments and motivate continued learning.
External Documentation
| Resource | Link |
|---|---|
| Official API Docs | OpenBadge API Docs |
| Specification | 1EdTech Open Badges v3.0 |
Key Concepts
| Concept | Description |
|---|---|
| Badge | A credential definition (what it represents, criteria to earn it) |
| Issuer | The organization or app that issues badges |
| Assertion | A badge awarded to a specific student (the actual credential) |
| Verification | Cryptographic proof that a badge is authentic |
Common Use Cases
- Issue achievement badges: Reward students for completing courses or reaching milestones
- Create skill badges: Recognize mastery of specific competencies
- Verify credentials: Confirm that badges are authentic and unaltered
- Display earned badges: Show student achievements in profiles or portfolios
Essential Endpoints
| Endpoint | Purpose |
|---|---|
POST /badges | Create a badge definition |
POST /assertions | Issue a badge to a student |
GET /assertions/{id} | Retrieve and verify a badge |
GET /badges/{id} | Get badge definition details |
Examples
Create a Badge Definition
Request
curl -X POST $TIMEBACK_API_URL/ims/ob/v3p0/credentials/ \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://purl.imsglobal.org/spec/ob/v3p0/context.json" ], "id": "https://example.com/badges/math-mastery-level-5", "type": ["VerifiableCredential", "OpenBadgeCredential"], "issuer": "https://your-school.edu", "name": "Math Mastery Level 5", "description": "Demonstrated mastery of 5th grade mathematics", "image": { "id": "https://example.com/badges/math-mastery-level-5.png", "type": "Image" }, "credentialSubject": { "id": "https://example.com/achievements/math-mastery-level-5", "type": ["Achievement"], "name": "Math Mastery Level 5", "description": "Complete all 5th grade math units with 90% accuracy", "criteria": { "narrative": "Complete all 5th grade math units with 90% accuracy" } } }'const badge = await fetch(`${TIMEBACK_API_URL}/ims/ob/v3p0/credentials/`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ '@context': [ 'https://www.w3.org/2018/credentials/v1', 'https://purl.imsglobal.org/spec/ob/v3p0/context.json', ], id: 'https://example.com/badges/math-mastery-level-5', type: ['VerifiableCredential', 'OpenBadgeCredential'], issuer: 'https://your-school.edu', name: 'Math Mastery Level 5', description: 'Demonstrated mastery of 5th grade mathematics', image: { id: 'https://example.com/badges/math-mastery-level-5.png', type: 'Image', }, credentialSubject: { id: 'https://example.com/achievements/math-mastery-level-5', type: ['Achievement'], name: 'Math Mastery Level 5', description: 'Complete all 5th grade math units with 90% accuracy', criteria: { narrative: 'Complete all 5th grade math units with 90% accuracy', }, }, }),})Issue Badge to Student
Request
curl -X POST $TIMEBACK_API_URL/ims/ob/v3p0/issue-badge/ \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "achievementId": "https://example.com/achievements/math-mastery-level-5", "userId": "student-123", "awardedDate": "2025-11-22T10:00:00Z", "validFrom": "2025-11-22T10:00:00Z" }'const assertion = await fetch(`${TIMEBACK_API_URL}/ims/ob/v3p0/issue-badge/`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ achievementId: 'https://example.com/achievements/math-mastery-level-5', userId: 'student-123', awardedDate: new Date().toISOString(), validFrom: new Date().toISOString(), }),})