BadgeKit Tutorial

SueSmith edited this page Sep 25, 2014 · 37 revisions

BadgeKit supports various parts of the badging process, from creating badges to assessing applications for them and ultimately issuing them. Badge creation is made easy using templates and drafts, so you can work on badges at your own pace and involve colleagues in the process. Assessors can review badge applications and make awarding decisions by referring to badge criteria or rubrics.

This tutorial is aimed at helping people to use the BadgeKit app (using a self-hosted instance or hosted private beta account) at The app provides an admin user interface for badge issuing personnel (i.e. people who create and assess badges).

If you're a developer and want to work with BadgeKit, see the following resources:

The BadgeKit Glossary provides clear definitions of any badging terms you are unsure of. For answers to some Frequently Asked Questions about BadgeKit, visit the BadgeKit Help section.



Login to BadgeKit to begin. When you click Log In you will be prompted to sign in using Mozilla Persona - if you do not have a Persona account, create one now.

BadgeKit Directory Templates

Once logged in you will see your BadgeKit directory. Here you can access your badges, including drafts and templates.

Using the menu items, you can manage badges and applications, access help information and administer your account settings.

BadgeKit Badges Menu


The Badges menu provides quick links to badge templates and drafts, published badges and archived badges. You can start creating a new draft badge or template straight away. Notice that in each part of the directory, you can sort your badges in various ways to help find what you are looking for.

As you will see throughout this tutorial, BadgeKit models both badge templates and draft badges. We will explore more about these concepts as we go along. The following diagram provides a handy overview of the badging lifecycle - you may wish to refer to this when you start using BadgeKit.

Badge Lifecycle

Navigate to your badge Templates.



Templates are among the key features in BadgeKit - check out Templates make Open Badges even more open for an exploration of what templates can bring to badging.

Templates allow you to remix badges, re-using badge elements and speeding up the badge creation process. You can also use templates to work on badges collaboratively. A good way to get started using BadgeKit is to browse some of the templates you see listed. Click View to see the details for a template and Edit to reconfigure these details yourself. When you begin creating your own badges, the templates can provide a helpful starting point. Think of a template as a badge stencil or cookie-cutter - you use it to create a draft badge.

For example, you might create a template based on the type of skill the badge represents, such as soft-skills or achievements. Or you might create a template for a particular subject, such as art or science. With a template you only need to define those fields you plan on re-using, unlike a finished badge in which your data needs to be complete.

BadgeKit Directory Sort

When you approach the task of creating a new badge, you can either base it on an existing template or create a new template by clicking Start. You will then be able to use the template ingredients in future badges. View and edit some of the templates you see now.

To create a new draft badge based on an existing template, click Use. You can then edit the details and save your new draft.

Later we will look at badge editing in more detail.


BadgeKit facilitates collaborative badging - a key feature in this regard is the ability to share templates between systems. From the Templates directory, click to View a badge and switch to the Action tab.

Share Action

From the Action tab you can also edit, use or delete the template.

You will see a URL you can copy to import the template into a different system. Once you have copied the URL, switch systems, selecting the one you want to import the template into. Once in the other system, navigate to the Templates directory again. You will see the Import a template button near the top of the directory:

Import Template Button

When you click the button a pop-up will appear - paste your share URL in there.

Import Popup

Click Import and the template will now appear in your Templates directory.

Now let's look at draft badges - use the Badges menu to browse yours now.



Creating a new badge can take time and, as with templates, you may want to involve your colleagues in the process. Draft badges allow you to work on badges at a pace that suits you, adding and editing elements as you go along. You can share a draft badge for input from other people and don't need to publish it until you're completely happy with it.

BadgeKit Directory Drafts

The following diagram represents the badge creation process in BadgeKit, from template, to draft and finally published badge:

The Birth of a Badge

You do not need to follow this badge creation process - you can alternatively publish a new badge from a template or start a new draft badge without a template.

You will see some initial draft badges in the Drafts section in BadgeKit. Here you can View and Edit draft badges, or create a new draft by clicking Start.

Notice that in the directory, or when you choose View for a template, draft or published badge you can access various Actions. Actions for draft badges include Edit, Publish and Delete.

Draft Actions

Now browse to Published badges using the menu.



Published badges are available to earners - in your own site you can present a listing of published badges which earners can apply for (this is where BadgeKit API comes in). You can use the BadgeKit Web app to publish badges and manage their lifecycles, including reviewing applications for them. Use the links to Edit or View a published badge.

BadgeKit Published Badges

As you can see, you can also carry out various Actions on a published badge.

Published Badge Actions

You can issue the badge, copy its content into a new draft badge or archive it. When a badge is published, you can no longer edit it. BadgeKit will continue to save badges you work on as drafts until you publish, so you can work on them at a pace that suits you. If you want to create a slightly different badge based on a published badge, you can copy it into a new draft and make your changes there, before publishing the new badge.

Copying a badge will start a new draft initially populated with the content of the current badge. You can archive a badge if you no longer want it to be issued.

The Issue by Email option allows you to issue a badge directly to an earner email address. When you issue a badge in this way, BadgeKit will create a new badge instance associated with the earner email. Note that BadgeKit will not communicate with the earner when you issue a badge. The BadgeKit API will send notification to the issuer webhook when the badge is issued, including the badge assertion URL. At this point you can communicate with the earner in a manner of your choosing.

Navigate to your Archived badges.



As time passes, you may wish to archive badges. When you archive a badge, this stops it being issued to future applicants and also removes it from default display by the API. However, previous earners of the badge can continue to display and share it.

Archived Badges

When you archive a published badge, you can continue to access the data associated with it using BadgeKit. You can also copy the content of an archived badge into a new draft.

Notice the Create New option in the Badges menu - you can also use this to create a new badge at any time.

Create New

Whether you create a new draft badge, edit a draft badge or work on a template, you will see the same broad categories in which you define your badge elements. Let's look at these sections in more detail now.

You may find it easiest to start by editing an existing template, as some of the fields will already be filled in.

Editing Badges

You can give a name to each draft badge or template you work on. BadgeKit will save your edits as you work. Once you are happy with the content of a draft badge, you can Publish straight from the editing area.

Publish Warning

Notice that you can't edit a badge once it's published, however you can copy it into a new draft.

A badge includes several ingredients. As you can see, BadgeKit divides the parts of any badge you are working on into a few broad sections: Description; Options; Criteria; Milestone; Visual. You can access each of these using the tabs you see while editing.

The information displayed throughout the editing area provides additional guidance on the data items that make up a finished badge.

Let's look at each of the sections in turn, starting with the badge Description.


Badge Description Editing

Description fields provide information about what a badge represents. The Description fields include: the badge issuer; a short tagline-style description; tags for keywords related to the badge; a description for the badge earner; a description for the badge consumer.

Notes on description fields:

  • The description for earners focuses on helping people to decide whether or not they want to apply for the badge.
  • The description for consumers focuses on people who may end up viewing a badge when a successful earner displays or shares it.

Next switch to the Options tab.


Badge Options Editing

In the Options section, you can configure various properties and constraints on your badge. You can set time estimates for the badge, as well as selecting types, categories and standards. You can also optionally apply restrictions on your badge. For example, you may wish to limit how many people can earn the badge or how many times the same person can earn it.

Types and Categories

The types and categories you see in the BadgeKit Options section allow issuers to apply additional layers of classification to their badges. These are entirely optional and can be used to reflect your own badge issuing context.

As you will see from the drop-down list, the badge Type is a way to define the type of skill or achievement that the badge represents. Current types include Community, Skill, Knowledge and Showcase.

The Category list allows you to categorise the area of life or education to which the achievement represented by the badge applies. Current categories include Exploring Earth and Space, Work & Career, Community Action, Sport & Wellness, Design & Making, Media & Music, Performing Arts, Storytelling, Coding & Gaming, Numbers and Zoology.

The types and categories have been defined in consultation with partner organizations and will be developed to suit an increased range of issuers on an ongoing basis.

Standards Alignment

Notice that you can specify standards that a badge aligns to. You can add a name, URL and description for each standard:

Standards Alignment

Now let's look at the Criteria tab.


Badge Criteria Editing

The Criteria for a badge define the requirements for earning it. The criteria you enter may be viewed by potential applicants and by reviewers assessing applications for the badge.

You can specify the evidence applicants must submit in order to apply for the badge, choosing an optional type of evidence (which can be URL, Text, Video, Photo or Sound). You can include notes for assessors to help them when they review applications, as well as links to rubric material relevant to the badge's assessment.

Use the drop-down list to configure the number of criteria items you want to define for a badge and define whether or not each item is required to earn the badge.

Next switch to the Milestone tab.


Badge Editing Milestone

You can define milestones for badge earners. When an earner successfully acquires a particular set of badges, they can be automatically issued a milestone badge. This allows you to acknowledge higher-level experiences and skills. Conversely, a milestone badge allows you to create smaller, more granular badges that culminate in this badge.

In BadgeKit, select the Yes radio button to classify a draft as a milestone badge. The editor will then present a field in which you can specify how many badges are required to earn this milestone badge. You can then click the + button to choose existing badges which will count towards this milestone badge.

Milestone Badge Chooser

Select badges using the checkbokes that appear next to them in the list. Closing the pop-up will show the badges you selected within the Milestone section of the editor.

BadgeKit Milestone Editing

Last but not least, let's look at designing the Visual aspect of a badge.


Badge Visual Editing

BadgeKit includes the tools to design a new badge from scratch by combining various visual elements - we've made it easy to create an effective, eye-catching badge, so you don't need to be an expert designer! However, if you do have a badge design prepared outside of BadgeKit that you want to use, you can upload it (images should be in PNG format, ideally 90 pixels wide).

Choosing Upload will allow you to select a file from your computer. Choosing the Design from Scratch option will take you to the badge design studio.

By configuring the shapes, background, text, icon and colors, you can tailor your design to reflect the nature of the badge as well as any existing visual styling approach you are working with. You can work on your design at your own pace, seeing the visual preview update as you make choices from the panel below.

Badge Design Studio

The first tab you will see is the Shape tab, via which you can select from a series of typical badge shapes.

Selecting the Background tab will allow you to upload a background image if you plan on using one - this isn't necessary, but some issuers use consistent backgrounds to keep their badges in line with their overall branding look and feel.

Badge Background

In the Graphic tab, you can choose from an extensive selection of meaningful icon images to clearly define the nature and purpose of your badge.

Badge Graphics

The Color tab can be a particularly useful tool to create a visually appealing badge design. Here you can choose from a range of carefully selected color sets, safe in the knowledge that the colors will complement one another successfully!

Badge Colors

While editing your badge, you can move and resize the graphic to suit. Use the handle at the top to move the graphic around the badge area:

Badge Graphic Moving

Use the handles you can see around the graphic to scale and resize it:

Badge Scale

Finally, the Branding tab allows organizations (such as cities) to assert consistent branding across a set of badges, using ribbons:

Badge Branding

If you want to start your badge design over again, just click the Clear Design button. To save your design, choose Save and Exit. As with all other aspects of your badge, you can return to work on the design anytime until you're ready to publish.

Badge Design Preview

When you navigate back to the directory for badge Drafts, you will see a preview of your design in the listing.

Badge Design Directory


Once a badge is published, people will be able to apply for it. You can review badge applications within BadgeKit using the Applications menu.

Badges you publish are made available for listing on your own site via the BadgeKit API. You can then allow earners to apply for a badge through your site, forwarding their application data to the API. At this point the application will appear in the BadgeKit app, in the Applications section.

To access any outstanding badge applications, choose Pending.


BadgeKit Applications Menu

Assessors can review badge applications in BadgeKit, viewing evidence and rubrics for the badge, as well as the optional notes you can define when you create your badges. The assessor can then submit their badge review in BadgeKit, at which point your own site can receive notification via the API webhooks. You can then communicate with the earner - hopefully offering them a badge following a successful application!

What a BadgeKit user sees in the Applications section depends on their account settings. Users can see applications for whatever systems, issuers or programs they have been granted permissions for. The pending application list displays each badge name, together with a link to its details, and links to any outstanding applications for it.

Pending Applications


Clicking a user application in the badge list will take you to the review section of BadgeKit. The first page displays the badge description. You can see the user email address at all times while reviewing. BadgeKit will save the review automatically if you leave the page idle.

Application Description

The Evidence tab is key to the application review - here you can see evidence submitted by the potential badge earner in support of their application.

Badge Application Evidence

The page displays an overview of what the applicant submitted when they applied for the badge, so that you can review whether or not they meet the badge requirements. Issuer sites connected to BadgeKit API will forward earner evidence when someone applies for a badge, with the evidence then visible within the pending application in BadgeKit.

The Criteria tab streamlines the process of reviewing a badge application by listing the badge criteria, each accompanied by a radio button to affirm or deny that the applicant meets the requirement and an indicator of whether or not the criteria is required.

Badge Application Criteria

You can opt to provide comments on individual criteria. If you mark each required criteria as being met by the applicant, BadgeKit will automatically process the badge application review as a successful one. In such cases you will see a graphic indicator of this via the little tick icon above the editable sections.

The Finish tab in the application review section of BadgeKit allows you to provide detailed feedback to the badge applicant, before submitting your review. You can cancel and exit at any time instead.

Application Finish

What happens next depends on how your own site is plugged into BadgeKit. The API notifies issuer sites via the webhook URL when an application is submitted. At this point you will likely want to forward the application review result to the earner, offering them the badge if the application was successful, forwarding feedback either way. As you will notice, when you submit a review, BadgeKit keeps the application in the pending list until the badge is actually awarded - this happens when the earner agrees to accept the badge.

For example, the following email is sent to successful applicants for badges that are part of the Open Badges project itself:

Application Email

The earner can then click to accept the badge, at which point the issuer site again communicates with BadgeKit API, this time to award the badge - the application will stop appearing in the pending list when this occurs. The API outputs another message when an issuer site makes the call to actually award the badge, at which point you can again respond to the event by contacting the earner directly. These API steps are in place so that you remain in control over all earner interaction with your badging system.

As you can see from the example email, a typical follow-up task is offering to let the earner push their new badge to their backpack - the Open Badges team is currently working on a new federated backpack, so watch this space for developments on that!

Account Settings

The login/account menu lets you configure your account settings and log out of BadgeKit. If you browse to your Settings, you will see that you can manage BadgeKit user accounts.

Account Settings

To manage user accounts, select a System, Issuer and Program (if you are using these admin levels).

Account Systems

Select System Users, Issuer Users or Program Users to manage accounts and permission levels. You can add user emails to any admin levels they need access to, which will determine what they see when they log into BadgeKit.

You can also configure permissions for each user within their System context - users can draft, publish and review.

User Permissions

Account Context

When you are logged into BadgeKit, what you see will depend on your current context. For example, if the same login gives you access to more than one system, issuer or program, you can toggle between them using the control at the top of BadgeKit.

System Context

This lets you browse badges and applications for particular systems, issuers and programs.

Context Switching

Additional Info

Navigate to the Help section in BadgeKit for additional information. Support is available through a variety of channels, just choose the option that suits you best! You may also like to watch our BadgeKit webinar trainings for a full walk-through of the tools.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.