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 Canvas Badges server administrator. These scopes or a subset of them will be available to you when you request authorization on behalf of a user of your app.

Profile Scope (Automatic)

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

Issuer Scopes

• r:issuer This 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:issuer This 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 Canvas Badges 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.

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 Canvas Badges user would like to grant you access to her badges, issuers and profile information. First, create a “Login with Canvas Badges” button on your website that links to the following URI (line breaks added for readability):

https://badgr.com/auth/oauth2/authorize?

client_id=123&redirect_uri=https%3A%2F%2Fexample.com%2Fauth&scope=r%3Aprofile%20rw%3Aissuer%20r%3Abackpack

Set client_id to the Client ID you received from the Canvas Badges team. Set redirect_uri to the Redirect URI for your application (url encode this and all parameters). 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 Canvas Badges 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 URL

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 Canvas Badges API  below.

Here is a diagram showing the initial authorization flow:

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 test sandbox environment's endpoints for testing. Use https://test.badgr.com/auth/oauth2/authorize and https://api.test.badgr.com/o/token. For more detailed information on OAuth2 read RFC 6749 https://tools.ietf.org/html/rfc6749. For production environments, HTTPS is required for redirect URIs, and localhost or developer machine tunnel domains are not permitted.