Badgr App Developers API Guide
Interested in making applications that work with Open Badges?
Quickstart: Issuing Open Badges with the Badgr API
Here are some guided examples through which you can learn how to use the Badgr API by showing you how to authenticate, create an Issuer, define a BadgeClass, and issue an Assertion. There are many more things that you can do with the Badgr API. See the full Badgr API Docs for a list of endpoints.
Authentication
Badgr uses OAuth2 for most operations. As an API client user, you may obtain an OAuth2 Bearer Token on behalf of your own Badgr user account using a password-based grant, or you can obtain such auth tokens on behalf of many users by registering your own Connected App. See more about registering for an app key and secret here.
Obtaining a Token
This guide will focus on getting started quickly, so we’ll use a password-based grant on Badgr’s US-based free hosted service badgr.io. You can also make these requests against a different Badgr server, such as Badgr’s EU-based eu.badgr.io server or an installation of badgr-server from the open source code. Request authentication by making a POST request to https://api.badgr.io/o/token
with your email address and password as the username
and password
request parameters. This request may be made with a JSON request body, form-data, or x-www-form-urlencoded.
For example, from cURL: curl -X POST 'https://api.badgr.io/o/token' -d "username=YOUREMAIL&password=YOURPASSWORD"
You’ll receive a document in response like the following:
{
"access_token": "YOURACCESSTOKEN",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "YOURREFRESHTOKEN",
}
Don’t have a password on your account? In order to use the password-based grant, you need to set a password on your account. You might not have one already if you created your account via sign-in from a external identity provider, such as Facebook or Google. You can add a password once signed in from your Profile page. If you don’t yet have an account, sign up for a free one here. You will need a verified email address to access the following APIs, so make sure to complete that step.
Authenticating requests with an OAuth2 Bearer token
Add an Authorization
header to each of the subsequent API requests with a value of Bearer YOURACCESSTOKEN
, (replacing YOURACCESSTOKEN with the value of the access_token
key in the above response).
You may use this token to request any API that your user has access to (the default “scope” you obtained above was very permissive – rw:profile rw:issuer rw:backpack
, so it can be used to make any of the API calls your user needs to make).
For example, in a request to retrieve the user’s own profile made from cURL, this header would be set like:
curl 'https://api.badgr.io/v2/users/self' -H "Authorization: Bearer YOURACCESSTOKEN"
Response Envelope
All responses from the V2 Badgr API that have a body wrap this body in a JSON response envelope that provides the resulting data of the request as well as metadata about the success or failure of the request. Result is always a list ([]
) even when there is only a single entity or no entities in the result.
An example successful response body:
{
"status": {
"description": "ok",
"success": true
},
"result": [
{
"entityId": "g66EErPYSZOyssbD79U3zB"
}
]
}
Each of the entities in the following examples will be returned upon successful creation will have an entityId
property that will be used to identify it for subsequent API calls (typically in the request path when creating or viewing related entities).
An example unsuccessful response body:
{
"status": {
"description": "bad request",
"success": false
},
"result": [],
"validationErrors": ["Form-level errors (crossing multiple fields) appear here."],
"fieldErrors": {
"name": ["This field is required."]
}
}
The validationErrors
and fieldErrors
properties only appear in the document when status.success
is false.
Issuer API
Some of the most important API calls that clients make against the Badgr API are to issue badges. Issuing manually via the web interface is great, but in order to scale your badge issuing programs, you’ve got to start automating, and the Badgr API makes it easy. Every badge is awarded by an Issuer, so we’ll start by creating an Issuer Profile, then we’ll define the BadgeClass to award, and finally we’ll award an Assertion of that BadgeClass.
Each of the three requests we’ll start with in this section is a POST request. We recommend using the API in JSON for both request body Content-Type
and response body content. By default if you do not specify an Accept: application/json
header, JSON will be returned.
Create Issuer Profile
Request Path: /v2/issuers
An Issuer Profile describes an organization or person that awards Open Badges. It is published as the Open Badges Profile class.
Properties:
name
is required: string.description
is required: string.url
is required. This should be a fully-qualified URL of a page that describes this issuer/program.image
is optional should be base-64 encoded strings and may only be PNG or SVG. For example, a small PNG image file should appear like this in request bodies that require an image field:"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mN0nmxRDwADvgGPapFGzwAAAABJRU5ErkJggg=="
email
must be a verified email on the authenticating user’s Badgr account. Get/v2/users/self
to retrieve your profile and see your verified email addresses.
Define BadgeClass
Request Path: /v2/issuers/:issuer_entity_id/badgeclasses A BadgeClass is a type of badge that an Issuer may award over and over (creating many Assertions of that BadgeClass, each for a different recipient). See Open Badges Specification: BadgeClass
Properties:
name
is required: string.description
is required: string.image
is required and may only be PNG or SVG format. For example, a small PNG image file should appear like this in request bodies that require an image field:"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mN0nmxRDwADvgGPapFGzwAAAABJRU5ErkJggg=="
- Criteria is required. One or both of
criteriaNarrative
(a markdown-formatted string) and/orcriteriaUrl
(a fully-qualified URL of a page representing the criteria for this badge) must be supplied. tags
is optional. If present, it should be a list ([]
) of one or more strings;alignments
is optional. If present, it should be a list ([]
) of one or more JSON objects that each have these properties:targetName
required, stringtargetUrl
required, fully-qualified URL stringtargetDescription
optional, stringtargetFramework
optional, string (what competency framework name does this alignment target fall under?)targetCode
optional, string (is there a sub-tag under the targetUrl that distinguishes this from other possible targets that you would identify with the EXACT same URL? Only use this if thetargetUrl
would be otherwise ambiguous.)
Issue Assertion
Request Path: /v2/badgeclasses/:badgeclass_entity_id/assertions
An Assertion is an instance of a BadgeClass (type of achievement recognized by an Issuer) that is awarded to one recipient. There might be many Assertions of a particular BadgeClass that an Issuer has awarded to different recipients. See Open Badges Specification: Assertion
Properties:
recipient
is required, (the only required property) and it must be a JSON object with at least anidentity
key. Other optional properties of therecipient
“IdentityObject” include:type
(what type of identifier isidentity
? Choose betweenemail
,telephone
, andurl
); andhashed
(boolean, should theidentity
be hashed in the final Open Badges Assertion?). When you GET the object back from the API,plaintextIdentity
, a read-only property appears to show you what your originalidentity
value was in case it is obscured behind the public-facing hash (whenhashed == true
).- Evidence may be expressed in terms of an overall “narrative” and/or one or more “evidence items”.
narrative
is an optional property that accepts Markdown-formatted strings.evidence
is a property that accepts a list ([]
) of JSON objects ({}
) that each have anarrative
and/or anid
(which is a URL to a piece of evidence hosted on HTTP) - Note that
image
is read-only on this endpoint. The “baked” image will be generated from the BadgeClass image by the server. issuedOn
is optional: you may override the issue date with a date in the past. Expects an ISO8601 formated datetime stamp including time zone identifier. e.g.2018-11-26T13:45:00Z
(In this case, “Z” stands for “Zulu”, UTC)expires
is an optional expiration date for the Assertion. Same format expectations asissuedOn
.notify
is an optional boolean property. Should the recipient be notified by email? (only functions with theemail
recipient type). Note: for required privacy disclosures, an email notification will be sent to the recipient upon the first award to each email address on a particular Badgr server.
Download our Postman Collection
Postman is a simple app that runs on Mac, Linux, or Windows that many developers use to make HTTP requests against APIs they are working with. It has a simple user interface that makes it possible to create a wide variety of API requests. We’ve created a postman “Collection” of the above API requests and documentation so that you can u
Download Badgr Basics Postman Collection
Instructions for use:
- Download the collection file
- Import collection into Postman (File > Import…)
- Configure Authentication. In the latest version of Postman:
- Edit the collection
- Navigate to the Authorization tab
- Select OAuth 2.0 for Type
- For “Add auth data to”, select “Request Headers”
- Click Get New Access Token
- Grant type: Password Credentials; Access Token URL: https://api.badgr.io (or your chosen badgr API root); Username: your email address; Password: your password; Client ID:
public
, Scope:rw:issuer rw:profile rw:backpack
- Confirm, Update (save) Collection
- Create an Environment, activate that environment (controls are in the upper-right of the Postman interface). Read more about Postman environments.
- Customize data in each of the endpoints to match the values you would like to send to the server, and submit requests.
Variables will be saved to the local environment after each of the Create Issuer and Define BadgeClass calls to set the resulting entityId to the environment, so subsequent calls to define BadgeClasses and award Assertions automatically use the last-set entity ID.
Updates to this collection will be published periodically. Contact @BadgrTeam on Twitter if you have suggested improvements.
Helpful Links
- Back to the App Developers guide
- See the full list of API endpoints at the Badgr API Docs.
- Download badgr-server (Python/Django) and badgr-ui (JavaScript/Angular) on GitHub.
- Sign up for a free account on Badgr.