From MozillaWiki
Jump to: navigation, search

Quick Start

If you or your organization has the technical resources, you can host Mozilla BadgeKit on your servers by downloading the code from Github - a tutorial for this process can be found here.

Alternatively, there are a number of other badge issuing options available if you wish to set something up sooner. Here are some services being offered from our issuing partners:

If you just want to play around with creating badges and are familiar with JSON syntax, check out the Badge Lab. It's a customized tutorial that walks you through creating your very own "hand-made" Open Badge.

Mozilla Open Badge Infrastructure (OBI)

NOTE: For a general introduction to badge issuing with the Mozilla OBI, read on. For more technical documentation, please see our github pages.


Why Are We Doing This?

Learning happens everywhere. Yet it's often difficult to be recognized for skills and achievements that are gained outside of school. Mozilla's Open Badges project is working to solve that problem by making it easy for anyone anywhere to issue, earn, and display badges. The results: broad recognition of 21st century skills and experiences, unlocking of career and educational opportunities, and learners everywhere being able to level up in their lives and work.


  • Develop badges as a system for alternative accreditation, credentialing, and recognition;
  • Help badges expand beyond siloed environments to be broadly shareable;
  • Truly support earners learning everywhere;
  • Optimize the value of these representations by allowing badges to be remixable and shareable with different audiences;
  • Develop a supporting infrastructure to standardize the process and support each earner;
  • Create an infrastructure that is open and as decentralized as possible to give earners control and support of the entire ecosystem;
  • Provide software and development tools to help organizations implement badging systems.


The Open Badges framework is designed to make badging flexible enough to represent the full range of learning and experience in online and offline life. This requires support for multiple, potentially significantly varied, badge issuers. Empowering earners to use their badges as legitimate credentials also requires support for sharing of badges across many display sites.

Earners can share badges across such varied online environments as personal blogs and social networking channels, tying a variety of achievements to a single identity. It is critical for the infrastructure to be open, to give earners control over how they represent their own learning and experiences, to allow anyone to issue badges, and for each earner to be able to carry their badges with them throughout their online life.

The participants in a badging system are characterized using a few broad groups:

  • Issuers - they create badges, make them available to earners and award them.
  • Earners - they apply for badges and decide where to display them.
  • Displayers - they display badges earned by particular earners (this also involves verifying badges).

You will see these roles described throughout the material you read on Open Badges. This page is aimed at providing an overview of badging for issuers, with an introduction to the technical aspects of issuing.

Last but not least, although not involved directly in badging systems, let's not forget this group of people:

  • Consumers - they include anyone looking at a badge (or badges) earned
    • examples include potential employers, college admin and peers.

Tech Specs

  • The OBI is built in node.js using express.
  • Badges are represented by JSON data blobs embedded in PNG files in the Backpack
  • Identity management is handled by Mozilla Persona

Open Badges Ecosystem

Open Badges -- Tech-diagram-v3 updated.png

Here's an overview of how badging works:

  • An issuer makes a badge available to their community of earners on their website. When awarded the badge, an earner sends it to their Backpack.
    • The badge becomes portable through the Issuer API script, presenting the earner with a modal dialog that requests their consent to add the badge to their Backpack.
    • If the issuer wants the earner to be able to store the badge outside the OBI, they can optionally push it to the Mozilla Baking Service where the assertion URL representing JSON blobs is embedded into PNG files. Otherwise badge baking is handled through the Issuer API.
  • Displayers pull unpacked badges (JSON) out of the Backpack based on earner action and privacy settings.
  • Public badges are discoverable based on earner’s email address, optionally through the Displayer API.
  • Earners can share their badges through their Backpack and grant permission for a particular site to display that collection of badges.
  • Displayers authenticate badges with the issuer using a verification check.

Badge issuing is significantly simplified using BadgeKit, Mozilla's new set of badging tools. The BadgeKit Web app lets issuers create and publish badges through an intuitive interface. An issuer can then present those badges using the BadgeKit API, which also handles reviewing applications - Read more about BadgeKit.

Definitions and Concepts


A digital representation of a skill, learning achievement or experience. Badges can represent competencies and involvements recognized in online or offline life. Each badge is associated with an image and some metadata. The metadata provides information about what the badge represents and the evidence used to support it.

Open Badge Infrastructure (OBI)

Open infrastructure technology supports independent badge issuers and displayers. Includes the metadata specification, APIs, verification framework, Backpack and software tools.



Someone who earns a badge (either by applying or being directly issued with it). The earner can use their Backpack to manage and share their badges.


Organization or individual who issues Open Badges to their community. The issuer is responsible for defining badges, making them available to earners and handling applications for them.

  • Badge issuing can involve participants with various specific roles, such as application assessors, badge creators and administrators.


A website, organization, or person who accesses publicly shared Open Badges and displays them for badge earners.


Mozilla Backpack

The core authorized data store and management interface of Mozilla’s reference implementation of the Backpack. Each earner has their own Backpack where their badge data is stored.

Assertion Specification

Badge metadata is represented as an assertion. The assertion specification defines the information within a badge. An assertion includes multiple items of data, such as: badge name and description, issuer, date, criteria URL, evidence URL and badge image URL. The assertion should carry all the information needed to process a badge. This ensures that badges can be fully understood and verified no matter where they are shared.

Badge Baking

A badge is an image combined with assertion data - badge baking embeds assertion data into an image to produce a portable badge.

Issuer API

The Issuer API provides a script for issuers to let earners send badges to the Backpack.

Displayer API

The Displayer API provides specifications for displaying badges beyond the Backpack.


Displayers are responsible for verifying badges, i.e. checking that a badge is valid and was issued to the person claiming it.


A new set of tools to simplify badging for issuers - provides an interface for creating and managing badges/ assessing badge applications. The BadgeKit API lets issuers control interaction with their own community of badge earners while supporting much of the badge admin process through a Web app.

See also the BadgeKit and Open Badges Resource list

To explore the concepts and terms in badging and badge issuing, check out the Badging and BadgeKit Glossary

Issuing Badges

An issuer is an organization or individual who designs and issues badges within the ecosystem. The OBI is open and supports any independent issuer who conforms to the necessary badge and issuing specifications. Additionally, issuers can now benefit from the BadgeKit tools, providing they meet specific technical requirements.


  • Issuers determine the badging approach that will work best for their communities.
  • Touchpoints with the OBI occur through interfaces, including sending badges to Backpacks and optionally using BadgeKit.
  • Issuers do not need to register with the OBI - they simply utilize the JavaScript APIs.


  • Issuers must have Web hosting facilities including:
    • A server capable of serving requests to the general Internet.
    • The ability to make a POST request from their server backend and read a JSON response.
    • Email addresses for earners (and the ability to email them).
    • Badges structured in the format that the assertion expects - when using BadgeKit this structuring is automated.
    • Earners must be registered with the backpack implementation that the issuer is trying to send their badges to. In the future, the issuer will need to ask the earner which backpack they want to push badges to and honor that request.
  • For verification:
    • For Hosted Assertions - issuers must maintain a server with the Badge Assertion information (at the unique badge URL) to verify each badge.
    • For Signed Assertions:
      • Issuers must generate public/private key pair and maintain the hosted public key.
      • Issuers must sign the badges themselves, sign the whole package, and push badges to earner backpacks through the Issuer JavaScript API.
  • Issuers looking to use BadgeKit have a specific range of options and requirements regarding hosting and technical provision - see the following blog post for more information: Announcing Mozilla BadgeKit.

Badge Creation Flow

Issuers need to:

  1. Have an email address for the earner.
  2. Create and host an assertion on site.
  3. Create and host the badge PNG; this is a single PNG for all badges, not a single physical PNG per issued badge.
  4. Integrate your site with the Backpack via the Issuer API

The Issuer API is a script that can be dropped into any badge issuer's website to provide a way for earners to add an issuer's badges to their Mozilla Backpack (or federated backpacks). There's no need to bake the badges independently as the API takes care of this.

The badge creation flow varies significantly for issuers using BadgeKit. Issuer admins can design and define the data for a badge within the BadgeKit Web app, with BadgeKit handling metadata structuring. Issuers can then present available badges to their earners using the BadgeKit API.

Open Badges related Widgets created by the community

A number of Open Badges widgets and utilities have been developed for integrating badges with various technologies including WordPress, Drupal, Django, Rails, PHP, Java, Moodle, Mahara, Joomla, Blackboard, Google Sites, Canvas, iOS, Android and AJAX.

See the list on GitHub (which is regularly updated).


BadgeKit builds on a range of tools which have been under continual development for some time, through projects such as Chicago Summer of Learning. These tools include Open Badger and Aestimia.


The Mozilla Backpack is an authorized data storage space and management interface for earners of Open Badges. Each earner can access their own Backpack - that lets them manage and share their badges.

  • The Backpack is open source and federated. Earners or issuers can take the code and fork it.
  • Earners may decide to create and host their own Backpack so that they have complete control over their badges.
  • Mozilla has built a reference or default Backpack (the "Mozilla Backpack") which holds all of the badge assertions (hashed user email + badge data) for each earner.


Badge metadata is defined as an assertion, which contains multiple required and optional fields. The structure has evolved over time - see the assertion specification for complete details.

Issuers can put a reasonable amount of extra material into a badge, but that material must be static - once the badge is issued, any change to the information must not change. This is to prevent someone from issuing one badge, then sneakily changing it later to another badge unbeknownst to the earner.

Badge Images and Baking

  • A baked badge is a JSON blob of metadata embedded in a PNG file.
  • This allows the badge to be more easily portable - a collection of information that can be emailed, carrying its details with it.
  • Ultimately, this is important for decentralization of the system and will allow earners to have more control over where their badges live.

Baking Service

  • To bake a badge, you must host a badge assertion on your site.
    • The system is designed to:
      • avoid SPAMing the earner with unwanted badges, and
      • give earners ultimate control over where the badges go.
  • Mozilla provides the "tools" for unpacking the PNG file through the OBI.
  • PNG files will be unpacked in the Backpack where each earner can view, manage, and organize their badges (and see all the metadata behind each badge).
  • PNG files are unpacked so that displayers just have the raw data to work with on their end.

If you are building a new system, we strongly recommend using the JavaScript Issuer API or BadgeKit for awarding badges. The tools and APIs take care of the badge baking.

Badge Image Standards

  • Image must be a PNG.
  • Images should be square and not exceed 256kb. They should have dimensions not smaller that 90 x 90.
  • Image is provided as a URL to the image on the issuer server, stored within the metadata.
  • Mozilla will cache the image in at least two sizes.
  • When a badge is displayed, it will be loaded from the Mozilla cache to avoid extra burden on the issuer servers. This also helps if the issuer is not available or the link is broken.
  • When using BadgeKit, issuers can design badges inside the Web app using a graphical tool, or can upload images prepared elsewhere.


Badge verification involves checking that a badge was issued to the person displaying it, using their email address. Verification affects both issuers and displayers.

  • To avoid gaming and duplication, the OBI is built to support badge verification.
  • This is essential to allow earners to prove the authenticity and validity of their badges. Badges can also have expiry dates, allowing organizations to issue badges for skills which are only valid for a set period of time.
  • The OBI provides the channel for this verification to happen through the Backpack, by communicating with the issuer.
  • Verification is typically carried out by displayers, who should not display a badge that cannot be verified.

Verification Method

The OBI currently supports verification of badges through hosted and signed assertions. The assertion data for a badge contains verification information. For hosted assertions, this includes a URL field representing the assertion hosted on the issuer's server. For signed assertions, it includes a link to the issuer's public key. Displayers can utilize this data to verify badge earners.

The verification process is as follows:

For hosted assertions:

  1. Displayer carries out a GET request on the verification URL from the assertion.
    • If the response is not 200 OK or if the data at the URL is not structurally valid, the badge is treated as invalid.
  2. Displayer analyses content of data at assertion verification URL, which includes recipient email address.
    • Verification can now be achieved by comparing the salted hash value for the recipient (according to the verification data) to the salted hash for the email of the person claiming the badge.
  3. The displayer can optionally check further information in the verification data, including an expiry date if there is one.

For signed assertions:

  1. Displayer unpacks JWS object specified in the assertion verification fields.
    • If the data fails to parse as JSON data, verification fails.
  2. Displayer extracts the verify.url property from the JSON, carries out a GET request on it and stores the public key.
    • If the HTTP status is not 200 OK, verification fails.
  3. Displayer uses the public key to perform JWS verification on the JWS object - if this fails, the badge is considered invalid.
  4. Displayer retrieves the revocation list and checks that the badge ID is not included.

For more about assertions and verification, see the Specification.

Note: for baked badges, verification also involves extracting the assertion URL from the badge image - see the Verifier for more on this.

Functional Flow

  1. Badge (including assertion) exists in the Backpack.
  2. User attempts to display badge via a display site widget.
  3. Display site takes the earner’s email and puts it through a salted hash function.
    • eg. hash (‘’ + salt)
  4. Display site compares the resulting value with the value indicated for the recipient in the badge metadata.
  5. If values match, badge is verified and displayer displays the badge. If not, displayer should reject the badge.


Displayers are key to the value of Open Badges for earners. The OBI is designed to support display of badges acquired in various different types of context, letting earners paint 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 earner controls where their badges are displayed through the Backpack.
  • Each earner can create collections of badges and share with displayers that have connected to the Displayer API.
  • Earners can also make badges public; those badges are discoverable by displayers if they have the earner's email address.
  • If a site has an earner's email address, they can query that person's Backpack for all of that earner's public badges. The response is a JSON representation of the badges.


  • Identity is a critical component because we need to recognize earners as they collect badges from different issuers.
  • It's important to us that identity be open and decentralized.
  • We are utilizing verified email as a form of identity through the Mozilla product Persona.
  • Many sites already use email addresses for logins, even those that don't generally collect them.
  • We don't need to retain any profile or personal information about the earner; all we need is their email address.

Verifying Identity in Backpack

  1. User validates identity to Mozilla's Verified Email.
  2. User creates an account with Mozilla (same as sync account).
  3. User asserts which email addresses he or she owns.
  4. User does an SMTP challenge (system emails user a token link they must click) to prove ownership.