Developers Guide

This section provides a set of technical resources to guide you through the processes of creating, issuing and displaying Open Badges. The Specification provides technical documentation and code examples. These guides will build on those examples.

For a quick nontechnical introduction to Open Badges see Get started with Open Badges »

How to Issue Badges: Technical Guide

Issuing Open Badges requires constructing and publishing a set of interconnected resources that follow the structure and guidelines set out in the Open Badges Specification. The properties that make up a badge’s metadata are split across these resources depending on where they apply. Together they form an Open Badge. For each badge awarded, there’s:

Open Badges Specification Updates

Some consequential updates to this structure are coming with the next version of the Specification, particularly enabling embedding of complete BadgeClass and Issuer Profile documents into an Assertion (and into baked badges). See current issues in progress for details.

Baking and Images

Test Badge

A graphic image is an important component of a digital badge, because it carries much of the symbolic weight and branding of the achievement and its Issuer. The Open Badges Specification defines specific methods for embedding Open Badges metadata into PNG or SVG image files. The data must be encoded into these files precisely to avoid interrupting the image display in traditional renderers like web browsers but must be discoverable by badge-specific inspection tools. Badge images should have a square aspect ratio, and it is recommended to be greater than 90x90 pixels in size but under 256kb file size for maximum compatibility. “Bakery” tools are available open source in multiple languages and via HTTP API. Read more about baking Open Badge images »

Open Badge Composition Tutorial

The techniques described here work for building one or two complete badges, but when you want to scale up to offering hundreds, you can embed these practices into code or start working with a hosted platform or web application software to handle creating badges.

Delivery and Display

Issuers deliver a Recipient baked Open Badge images, which she stores in a Backpack or other displayer, which verifies the content and display verified metadata to many Consumers who are interested in her accomplishments.

Badges Ecosystem Infographic

The Open Badges Ecosystem (by Erik Knutson, Concentric Sky, licensed CC-BY)

A Typical Issuing Scenario

Several staffers at an after-school club get together. They want to recognize learning that’s happening in their program with Open Badges. They:

Badge Issuing Flow in Detail

You can design a badge issuing flow to suit your organization and community of badge Recipients. The Open Badges tools and Specifications support the creation, validation, publication, assessment, issuing, and display of badges.

When a badge is awarded to an earner, these steps may be carried out:

Displayers may choose to prominently display Open Badges features by linking to a validator service to allow Consumers to check on demand to ensure that a badge has proper integrity. Because Open Badges are verifiable, Consumers should have easy access to these capabilities whenever they encounter badges. See more Information on Displaying Open Badges »

Issuing Requirements

Issuer organizations may use one of the available issuing platforms or establish their own Issuer service by running open source code or building their own application. To act as an Issuer service, you need:

Additionally, for signed Assertions, you need to: * Generate a public/private key pair and host the public key * Sign the badge Assertions when they are issued

See also the Issuer Checklist to ensure you’re not missing any steps or options in crafting your BadgeClasses and Assertions. Issuers should consider the following guidelines on badge images:

Badge Images


Badge Assertions may be revoked if the Issuer determines they were issued in error or no longer should be valid. For a hosted Assertion, revocation entails replacing the Assertion with a note declaring the reason for revocation. For signed Assertions, Issuers may create a revocation list with keys for each of the UIDs they wish to revoke. A revocation list is a single JSON document for the entire issuer.

See notes on revocation in the Open Badges Specification for more information.

Issuer Insignia

Declare your support for Open Badges with Issuer insignia for your website. Show the world your badges align with the Open Badges and that they should expect the full range of Open Badges features when they see badges referenced on your site.

Issuer Banner & Ribbon

Download Issuer Insignia »


Verification is the process of ensuring that a badge meets the requirements of the Open Badges Specification. Although as an Issuer you may not be displaying earned badges, proper implementation of the Open Badges Specification allows those who seek to understand badges to justify placing trust in these records through strong verification.

The identity section of a badge Assertion includes the Recipient’s email address, a hash of the Recipient’s email address, or a salted hash of the Recipient’s email address. A Displayer can compare this value to the expected email(s) of the Recipient claiming the badge to establish authenticity. This facilitates verification, while preventing the need to store the earner’s email explicitly within the badge Assertion, providing protection against routine forms of unauthorized access.

For signed Assertions, validators use the public key to carry out a verification check. Issuers can also revoke signed badges, in which case a revocation list is created, including the UIDs for revoked badges - Displayers can check this list in case a badge has been revoked. See Revoking Issued Signed Badges.

To determine the credibility of an Open Badge, Consumers can inspect and validate the badge with an Open Badges validator tool, often one built into the display platform where they see a badge, to determine whether it’s valid, and that it belongs to the expected Recipient.

A good Open Badges validator ensures a number of checks pass:

Read more about validation in the Open Badges Specification.

Here are some available validation tools:

How to Display Badges

Badges are meant to be shared. Through the process of badge Recipients sharing information about their achievements with selected Consumers, those Recipients can turn their badges into new opportunities, promotions, informal recognition, and other forms of value in their work and recreational relationships. Badge Displayers create opportunities for Recipients to share the badges they’ve earned. With the Recipient’s email address, the Displayer can retrieve badges the Recipient’s been awarded and chosen to make public. How the Displayer processes a badge is determined by how it was retrieved and what form its Assertion takes. The Displayer can parse the data associated with each badge, verify it for authenticity, and display it in websites, applications, or social media posts. The displaying of badges can benefit and connect Recipients and Consumers. For example, a Recipient’s badges can signal achievement to a potential employer, which may be seeking an individual with the credentials and skills displayed by the Recipients.

Open Badges makes it possible for Recipients to display badges acquired in various contexts, painting a more detailed, complete picture of their skills and experiences. Badges are not siloed or limited to one site but can be combined with badges from multiple Issuers and then shared for different audiences and purposes. Each Recipient controls how and where his/her badges are displayed through a Backpack. See more about Backpack Services »

To display badges in your own applications you need:

The Mozilla Backpack Displayer API is a good example of display capabilities available to developers. With the Mozilla Backpack Displayer API, you can query that Backpack for public badges awarded to a particular Recipient. Information about the badges is returned in JSON, which you can use to render a wide variety of displays. Other Backpack have their own APIs for retrieving badge data for display in connected applications, though community members hope to converge on some simple functionality to be available from all backpacks in 2017 in order to enable developers of display applications to work with any compliant backpack service where badges are stored. To access development documentation and build your own application:

Ways to Display Open Badges from Backpacks:

Displayer capability from different backpacks varies per application.