Issuer API

The Issuer API is a script that can be dropped-in to any badge issuer's website to provide a way for users to add an issuer's badges to their backpack.

Methods

The Issuer API provides the following methods.

OpenBadges.issue(assertions, callback)

Presents the user with a modal dialog that requests their consent to add the issuer's badge(s) to their backpack. If the user is not currently logged into the backpack, they will first be asked to log in or create an account if necessary.

• assertions is a list of URLs that represent badge assertions.
• callback is a function that will be called when the user has completed their interaction with the modal dialog. The function is passed two positional arguments:
  • errors is a list of objects that provide information about any assertions that weren't able to be added to the user's backpack. Each object contains the following keys:
    • url is the URL of the assertion that couldn't be added to the user's backpack.
    • reason is an Error Constant String identifying the reason the assertion couldn't be added to the user's backpack.
  • success is a list of badge assertions that were successfully added to the user's backpack.

Error Constant Strings

• DENIED means that the user explicitly denied the badge from being added to their backpack.

• EXISTS means that the badge is already in the user's backpack.

• ASSERTION-NOT-ACCESSIBLE means that the assertion URL provided could not be retrieved. For instance, the assertion URL itself may be malformed, or attempting to access the assertion may have resulted in 404 Not Found or 403 Forbidden.

• ASSERTION-MALFORMED means that the assertion URL provided exists but was malformed.

Threat Model

The reason we're even presenting the user with a dialog is because we want to prevent badge spamming, whereby third-party issuers spam a user's backpack with badges that they don't want. Consequently, we need the backpack to ask for the user's consent. This will be accomplished via an iframe embedded in the issuer's page.

The only sensitive information that a user needs to enter in this flow is login credentials. Since authentication is done via BrowserID, which opens in a pop-up window, the consequences of spoof attacks are minimal–so long as the user knows to look at domain names in their address bar and BrowserID's UI.