Unofficial Badge Connect Guide

A developer resource for implementers of Open Badges 2.1

Badge Connect API, released as Open Badges 2.1 brings the concept of a Federated backpack to the Open Badges ecosystem. A backpack is a service that acts as an agent for a recipient of Open Badges. The full Badge Connect specification is available for participants in the IMS workgroup and will be published by IMS Global on its finalization in early 2020. Badge Connect was developed in 2018-19 by members of the IMS Global Open Badges Workgroup, based on years of thinking and advocacy for an open ecosystem by members of the Open Badges project founded by Mozilla.

You can view code examples of each section of the guide. (In Progress)

This guide is sponsored by the Badgr Team at Concentric Sky and licensed openly under Apache 2.0. Contributions welcome on GitHub.

Editor: Nate Otto (Concentric Sky / Badgr - USA)

Application Types

Applications in the Badge Connect-enabled Open Badges ecosystem fall into two main roles. Host (Backpack) and Relying Party. Relying Party applications typically serve functions as either an Issuer of badges, which provides recognition to recipients, or a Displayer of badges, which helps make badges meaningful or translate them back into some kind of real world value or new opportunity for their earners.

What is a Host (Backpack)?

A Host is the official role name in the Open Badges Specification, commonly called a Backpack, which stores badge award data on behalf of recipients, making it possible for those recipients to organize and manage the badges they have earned. Backpacks may allow sharing to social media sites as a means of transmitting information about the achievements that a learner has gained.

Examples of Issuer-role Applications

There are numerous reasons why an application would award badges. Badges can be used to recognize any achievement, large or small. Some example use cases include:

Examples of Displayer-role Applications

The first thing to understand about applications in the role of Displayer, is that Displayer is a clearly understood term for a vast category of applications that could make use of credentials earned by individuals, processing that credential data on behalf of badge recipients to provide them and others information about the meaning of these awards.

Examples of simple Displayer applications include:

Farther-reaching Displayer applications include:

These examples were provided by the participants of a Badge Connect workshop at the 2019 ePIC Conference in Lille, France and by contributors to this guide.

Badge Connect Applications

This section of the guide will explain how to get started with a relying party application for Badge Connect. Both Issuer apps and Displayer apps need to go through several common processes before the workflows for their specific needs diverge. Here we will explain these steps, including:

  1. Backpack Selection
  2. Dynamic Client Registration
  3. The OAuth Dance: Authorization Code & Token Exchange
  4. Refreshing Tokens

Then the remaining sections of the guide will provide step-by-step instructions for accessing the API endpoints necessary to build Issuer and Displayer applications.

Issuer Applications: What you Need to Know

Here is a guide for how to build a prototypical issuer application that awards Open Badges and pushes them to a recipient’s backpack of choice.

Issuer Apps step by step

Displayer Applications: What you Need to Know

Here is a guide for how to build a prototypical displayer application that pulls badge awards from a recipient’s backpack of choice and does something interesting with them. This example use case will be to display badges on a timeline to the user.

Displayer Apps step by step