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 react to events in their own domain to award new badges to users.
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.
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
- 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.
- 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_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
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 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"
And that’s it! You can store the access token in your application. Here is a diagram of this dance:
Note: If you have given us a
localhost Redirection URI remember to use our staging endpoints for testing. Use
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.
Using The Badgr API
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.