Using the Issuer API

With the Issuer API, you can push earner badges to the Mozilla hosted Backpack. This tutorial will walk you through the process of sending earner badges to the Backpack via the Issuer API script. The API handles getting the earner's permission to push to their Backpack, so your own code only has to pass the details of badges you are trying to send, then if necessary retrieve the response from the API.

In order to use the Issuer API, you must have your badge assertions stored as hosted files (at a stable location) or as JSON Web signatures. To find out more about assertion structure, see the current assertion spec.

If you're completely new to badge issuing, see Open Badges Onboarding: Issuers and if you're new to badge assertions, check out Assertion Information for the Uninitiated.

Contents

• Prepare your assertions
• Include the Issuer API Script
• Accessing the API
• Push to the Backpack
• Callbacks
  • Errors
  • Success
• User Flow

Prepare your assertions

To push a badge to the earner's Backpack, you first need to have an assertion prepared. An assertion represents a single badge awarded to a single earner. You can push both signed and hosted assertions to the Backpack using the Issuer API.

For hosted assertions, you need to have your three assertion files (badge assertion, badge class and issuer organization) stored at stable URLs - you will pass the URL for the badge assertion to the Issuer API endpoint. Your assertions must be able to respond to both GET and HEAD requests.

For signed assertions, you will pass the signature string to the Issuer API, so will need it prepared before you call on the Issuer API endpoint.

You can pass more than one assertion at a time if you wish to push multiple badges to the earner's Backpack, as the API expects an array.

You can validate both hosted and signed assertions using the Validator.

Note: Some proposed changes to the assertion specification are currently under discussion. See these threads in particular:

• Representing assertion objects inline
• Extending the assertion structure

Include the Issuer API script

To access the Issuer API, include a link to the script in your site or application:

<script src="https://backpack.openbadges.org/issuer.js"></script>

You can then access the API methods within your own code via the OpenBadges object.

Accessing the API

The API provides two methods for pushing assertions to the earner Backpack: issue and issue_no_modal.

Earners have complete control over their own Backpacks, so you can only push a badge to the Backpack with the earner's permission. When you call one of the issue methods, the earner will be presented with a dialog asking if they want to push the badge to their Backpack (it handles prompting the earner to log in or create an account etc).

• The issue method presents the dialog in a modal format within the page and allows you to indicate a callback function where you can receive the results of the user interaction with their Backpack.
• The issue_no_modal method presents the dialog in a full window rather than within the current page. This method does not allow you to define a callback function, but is typically more compatible with older browsers.

In certain browsers, the issue method will behave the same way as the issue_no_modal method.

Push to the Backpack

Use the issue or issue_no_modal method to push your assertion(s) to the earner Backpack in JavaScript as in these examples (for a single assertion - for multiple assertions just add more to your array parameter):

Hosted assertion, modal dialog:

OpenBadges.issue(['http://yoursite.com/badge-assertion.json'], function(errors, successes) {
	//...
});

Hosted assertion, no modal:

OpenBadges.issue_no_modal(['http://yoursite.com/badge-assertion.json']);

Signed assertion, modal dialog:

OpenBadges.issue(['abcdeFGHIJ12345.abcdeFGHIJ12345abcdeFGHIJ12345._abcdeFGHIJ12345-abcdeFGHIJ12345'], function(errors, successes) {
 //..
});

Signed assertion, no modal:

OpenBadges.issue_no_modal(['abcdeFGHIJ12345.abcdeFGHIJ12345abcdeFGHIJ12345._abcdeFGHIJ12345-abcdeFGHIJ12345']);

• For hosted assertions, include the URL(s) of the badge assertion(s).
• For signed assertions, include the signature string (which includes the encoded header, badge assertion and signature).

Callbacks

If it is called, your callback method will receive an indicator of errors or success pushing the earner's badge to their Backpack.

If successful, your callback will receive the list of assertions (URLs or signature strings) for the badges added to the earner Backpack (via the second parameter to the function, successes in the example). Otherwise, your callback will receive a list of errors (via the first parameter - errors in the example), including each assertion that was not added to the Backpack, together with the reason.

Errors

If your assertions are not pushed to the earner Backpack, the API will send an array of objects indicating why. Each item will include the assertion that was not added and the reason it wasn't added. For example, for a hosted assertion:

[
	{
		"assertion":"http://yoursite.com/badge-assertion.json",
		"reason":"EXISTS"
	},
	...
]

Or for a signed assertion:

[
	{
	"assertion":"abcdeFGHIJ12345.abcdeFGHIJ12345abcdeFGHIJ12345._abcdeFGHIJ12345-abcdeFGHIJ12345",
	"reason":"EXISTS"
	},
	...
] 

In this case the reason was that the badge already exists in the earner's Backpack. The API may return any of the following constant strings as reason for an error:

• DENIED - The user denied permission to add the badge.
• EXISTS - The badge is already in the earner's backpack.
• INACCESSIBLE - The assertion provided could not be retrieved.
• e.g. The assertion URL itself may be malformed, or attempting to access the assertion may have resulted in 404 Not Found or 403 Forbidden.
• MALFORMED - The assertion URL provided exists but was malformed.
• INVALID - The assertion URL provided exists and is well-formed, but is not valid.
• e.g. The recipient of the assertion may not be the currently logged-in user.

Success

If your attempt to push the badge(s) to the earner Backpack was successful, the API will simply return the assertions added (URLs or signatures). You can then respond in whatever way suits your own application.

User Flow

This is what happens from the earner perspective. When you call issue the modal is presented within the browser page:

The earner can then log into their Backpack if necessary:

Once logged in, the earner is prompted to accept the badge:

Confirmation is returned to the earner:

If the earner then browses to their Backpack, they will see (and be able to manage) the new badge. When the earner clicks "Thanks" in the above dialog, they are returned to your page, where the callback function will execute.

The Backpack will also indicate errors to the earner, for example:

This user experience applies to using the methods above, via which the earner must grant consent each time you attempt to push a badge to their Backpack. You may alternatively want to check out the Backpack Connect API, through which you can maintain a persistent session for the earner's Backpack, allowing you to acquire earner permission once, then push multiple badges without requiring repeated permission each time.