Connected App Developers

Interested in making applications that work with Open Badges?

What is a Badgr Connected App?

A Badgr Connected App is any web service that makes use of Open Badges as an issuer or displayer. If you want to bring verifiable achievements into your ecosystem, connect to Badgr’s API.

Issuer Apps

Issuer apps react to events in their own domain to award new badges to users.

Displayer Apps

Displayer apps help users display and interact with the badges they already have.

Connecting to Badgr

API Access with OAuth2

Badgr offers OAuth2 Identity Provider functionality to help your Connected App securely obtain a user-specific API token to use to access that user’s badges. Add a Connect to Badgr or Login with Badgr button to your service. The difference between Badgr’s identity provider and Facebook’s (for instance) is that there are many Badgr servers deployed in the world. In order to sign OAuth requests to a particular Badgr server, your service needs to establish a shared secret with the administrator of that Badgr server.

You can build apps that connect with badgr.io! Contact Concentric Sky to request an application key and secret for signing your OAuth requests. Describe what you’re planning on building and what type of information you need from Badgr users.

Get your key

Each badgr-server administrator manually adds new developer keys and secrets. The ability to automatically obtain a key and secret for certain scopes is on the Badgr roadmap for future development to allow rapid scaling of the Badgr Connected App ecosystem while carefully maintaining user privacy and control over their data.

Permission Scopes

Issuer and displayer apps need some combination of permissions to issuer and backpack (recipient) API endpoints. These are accomplished by requesting a set of permission scopes when you register your application with the Badgr server administrator. These scopes, or a subset of them will be available to you when you request a new auth_code token for a particular user.

Profile Scope (Automatic)

  • r:profile This allows you to get information about the user that they have defined in Badgr, including their firstname, lastname, and registered email addresses. This scope is automatically available. It gives you the ability to access the /v2/user/profile endpoint.

Issuer Scopes

  • r:issuerThis allows you to get information about the issuer profiles where the authenticated user acts as a staff member, editor, or owner. You may view issuer metadata, badges defined by these issuers, and badge awards granted by these issuers.
  • rw:issuerThis allows read/write access to the resources above, to the extent that the authenticated user may perform these actions. "Staff" level users may read all data and award new instances of defined badges; "Editor" level users may also define new BadgeClasses and edit existing ones. "Owner" members may modify the staff list.

Backpack Scopes

  • r:backpack Allows you to read assertions that the user has received from issuers on this Badgr server or imported into their backpack from external Open Badges issuers.
  • rw:backpack Allows you to read, create, and update assertions and collections of assertions. For assertions, this means you can trigger import of an Open Badges assertion defined elsewhere, pushing it to the recipient’s backpack.

As the open source project develops, the number of scopes will increase and become more granular. For example, issuer scopes will be broken down into specific actions that an app may request to perform, such as awarding existing badges, reading badge award history, defining new badges. Permissions for specific badges may be granted as well, resulting in a scope following the pattern of rw:badgeclass:ENTITY_ID

The OAuth2 Dance

Once you have emailed us your Scope and Redirect URIs and we have replied with a client_id and client_secret—we can dance. Suppose a Badgr user would like to grant you access to her badges, issuers and profile information. First, create a “Login with Badgr” button on your website that links to the following URI:

https://badgr.io/auth/oauth2/authorize?
client_id=123
&redirect_uri=https://example.com/auth
&scope=r:profile rw:issuer r:backpack

Set client_id to the Client ID you recieved from the Badgr team. Set redirect_uri to the Redirect URI for your application. We use this to redirect the user back to your website with an Authorization Code after they have logged in and granted you access. Set scope to the level of access you are requesting.

After badgr.io redirects the user back to your application with the Authorization Code in the query parameter code your application will need to exchange that temporary code for a long-lived Access Token via a POST request. Here’s an example using curl:

curl https://api.badgr.io/o/token -d \
"grant_type=authorization_code\
&code=XYZ\
&client_id=123\
&client_secret=ABC\
&redirect_uri=https://example.com/auth"

Note: you may pass a state parameter, which should be a URL-safe URL-encoded string. For example, you may encode a small snippet of JSON. This parameter will be passed back to you at your Redirect URI.

Exchange this authorization_code for an access token.

curl https://api.badgr.io/o/token \
-d "grant_type=authorization_code&code=authorization_code"

And that’s it! You’re done. You’ll receive a document like this:

{
    "token_type": "Bearer",
    "access_token": "C1HePsbwS3tUmwC6OCKsC41w96xckc",
    "expires_in": 86400,
    "refresh_token": "xwHPFwH55tQpCy3qCgsIW59k3g3aPh",
    "scope": "rw:issuer rw:profile rw:backpack"
}

And that’s it! You can store the access token in your application. You may now use the access_token obtained from this request to authenticate API requests. See Using the Badgr API below.

Here is a diagram showing the initial authorization flow: Diagram of the OAuth2 Dance

Your access token will expire (by default, 24 hours after issue). At that point, you may refresh it using the refresh_token included with the token. Refresh tokens are long-lived and must be stored securely. Access tokens also must be stored securely, but are lower risk due to their shorter duration. You may obtain a new access token using your refresh token by making a new POST to the authorization endpoint.

curl https://api.badgr.io/o/token -X POST -d \
"grant_type=refresh_token&refresh_token=YOURREFRESHTOKEN&client_id=YOURCLIENTID&client_secret=YOURCLIENTSECRET"

You will get back a new token document, including a new access_token and refresh_token. The new access token will be valid for the identified number of seconds.

Note: If you have given us a localhost Redirection URI remember to use our staging endpoints for testing. Use https://staging.badgr.io/auth/oauth2/authorize and https://api.staging.badgr.io/o/token. For more detailed information on OAuth2 read RFC 6749.

Launch Points in Badgr with LTI  COMING SOON!

Once your users connect your application, they’re going to want to see it at relevant points within the Badgr application. In order to facilitate this, Badgr is adding the ability for connected applications to register Learning Tools Interoperability (LTI) launch points. Your “tool provider” will define a set of launch locations from what Badgr has defined, and once a user has approved your application, an action button will appear in those places that will allow the Badgr user to open your application to a specific point.

Once this feature is complete, you’ll coordinate with the Badgr admin to register what launch points your application will use, and what the launch URL will be. When a user selects one of your LTI launch actions, you will received a key and secret.

More info on LTI at the IMS Global website.


Using the Badgr API

Quickstart View the Badgr API Docs

To authenticate a request using an OAuth token use the Authorization header with a value of Bearer, a space character, then the token you have obtained. E.g. Authorization: Bearer cZTp1ZMMSasZ4mbP2u2Pjt4NH3AVIf

Requests to the /v2/ API are all returned by default in JSON with a default response envelope. If successful, the result key will have a [] list of result objects, and single results will appear as a single entry within this JSON array. Try out the OAuth flow and making requests by creating a free account and clicking the Authorize button on the API Docs.