Instructure Developer Documentation Portal
Community
  • Introduction
  • Services
    • Elevate Standards Alignment - AB Connect API
      • Introduction
        • Authentication
        • Addressing Object Properties
        • Requesting Additional Properties in the Response
        • Filtering Using ODATA Like Statements
        • Sorting
        • Facets
        • Paging Data
        • Call Throttling
        • Working with Related Object
        • Error Responses
        • Character Set Support
        • How To Articles, Recommendations and Suggestions
        • Examples
        • Using AB Connect's Embeddable Widgets
      • Reference
        • Standards
        • Standard Collections
        • Events
        • Topics
        • Concepts
        • Assets
        • Asset Definitions
        • Asset Collections
        • Managing and Predicting Relationships
        • Providers
    • Canvas LMS
      • Basics
        • GraphQL
        • API Change Log
        • SIS IDs
        • Pagination
        • Throttling
        • Compound Documents
        • File Uploads
        • API Endpoint Attributes
        • Masquerading
      • OAuth2
        • OAuth2 Overview
        • OAuth2 Endpoints
        • Developer Keys
      • Resources
        • Access Tokens
        • Account Calendars
        • Account Domain Lookups
        • Account Notifications
        • Account Reports
        • Accounts
        • Accounts (LTI)
        • Admins
        • Analytics
        • Announcement External Feeds
        • Announcements
        • API Token Scopes
        • Appointment Groups
        • Assignment Extensions
        • Assignment Groups
        • Assignments
        • Authentication Providers
        • Authentications Log
        • Blackout Dates
        • BlockEditorTemplate
        • Blueprint Courses
        • Bookmarks
        • Brand Configs
        • Calendar Events
        • Collaborations
        • CommMessages
        • Communication Channels
        • Conferences
        • Content Exports
        • Content Migrations
        • Content Security Policy Settings
        • Content Shares
        • Conversations
        • Course Audit log
        • Course Pace
        • Course Quiz Extensions
        • Course Reports
        • Courses
        • Custom Gradebook Columns
        • Developer Key Account Bindings
        • Developer Keys
        • Discussion Topics
        • Enrollment Terms
        • Enrollments
        • ePortfolios
        • ePub Exports
        • Error Reports
        • External Tools
        • Favorites
        • Feature Flags
        • Files
        • Grade Change Log
        • Gradebook History
        • Grading Period Sets
        • Grading Periods
        • Grading Standards
        • Group Categories
        • Groups
        • History
        • InstAccess tokens
        • JWTs
        • Late Policy
        • Learning Object Dates
        • Line Items
        • LiveAssessments
        • Logins
        • LTI Launch Definitions
        • LTI Registrations
        • LTI Resource Links
        • Media Objects
        • Moderated Grading
        • Modules
        • Names and Role
        • New Quiz Items
        • New Quizzes
        • New Quizzes Accommodations
        • New Quizzes Reports
        • Notification Preferences
        • Originality Reports
        • Outcome Groups
        • Outcome Imports
        • Outcome Results
        • Outcomes
        • Pages
        • Peer Reviews
        • Planner
        • Poll Sessions
        • PollChoices
        • Polls
        • PollSubmissions
        • Proficiency Ratings
        • Progress
        • Public JWK
        • Quiz Assignment Overrides
        • Quiz Extensions
        • Quiz IP Filters
        • Quiz Question Groups
        • Quiz Questions
        • Quiz Reports
        • Quiz Statistics
        • Quiz Submission Events
        • Quiz Submission Files
        • Quiz Submission Questions
        • Quiz Submission User List
        • Quiz Submissions
        • Quizzes
        • Result
        • Roles
        • Rubrics
        • Sandboxes
        • Score
        • Search
        • Sections
        • Services
        • Shared Brand Configs
        • SIS Import Errors
        • SIS Imports
        • SIS Integration
        • Smart Search
        • Submission Comments
        • Submissions
        • Tabs
        • Temporary Enrollment Pairings
        • User Observees
        • Users
        • What If Grades
      • Outcomes
        • Outcomes CSV Format
      • Group Categories
        • Group Categories CSV Format
      • SIS
        • SIS CSV Format
      • External Tools
        • LTI
          • Introduction
          • Registration
          • Launch Overview
          • Configuring
          • Variable Substitutions
          • Deep Linking
          • Grading
          • Provisioning
          • PostMessage
          • Platform Notification Service
          • Placements
            • Placements Overview
            • Navigation
            • Homework Submission
            • Editor Button
            • Migration Selection
            • Link Selection (Modules)
            • Assignment Selection
            • Collaborations
        • xAPI
        • Canvas Roles
        • Plagiarism Detection Platform
          • Overview
          • Plagiarism Detection Platform Assignments
          • Plagiarism Detection Platform Users
          • Plagiarism Detection Submissions
          • Webhooks Subscriptions for Plagiarism Platform
          • JWT Access Tokens
      • Data Services
        • Live Events
          • Overview
            • Introduction
            • Setup
            • Caliper
            • Metadata
          • Event Format
            • Canvas
              • Account
              • Asset
              • Assignment
              • Attachment
              • Content
              • Conversation
              • Course
              • Discussion
              • Enrollment
              • Grade
              • Group
              • Learning
              • Logged
              • Module
              • Outcome
              • Outcomes
              • Plagiarism
              • Quiz
              • Rubric
              • Sis
              • Submission
              • Syllabus
              • User
              • Wiki
            • Caliper IMS 1.1
              • Assessment
              • Basic
              • Forum
              • Grading
              • Navigation Events
              • Session
    • Catalog
      • APIs
        • Analytics
        • Bulk Enrollments
        • Catalogs
        • Certificates
        • Completed Certificates
        • Courses
        • Email Domain Set
        • Enrollments
        • Orders
        • Programs
        • Progresses
        • Tags
        • User Registrations
        • Users
        • Waitlist Applicants
    • Credentials
      • Getting Started
      • Authentication
        • Password-Based Authentication
        • Authorization Code-Based Authentication
      • Pagination
      • APIs
        • Assertions
        • Backpack
        • Badgeclasses
        • Issuers
        • Organizations
        • Users
      • Release Notes
    • Data Access Platform
      • Key Concepts
      • Data Formats
      • Rate Limits & Policies
      • Datasets
        • Namespaces
          • canvas
            • canvas types
          • canvas_logs
          • catalog
        • Additional Notes
        • Entity Relationship Diagram
      • Query API
        • Authentication
        • Reference
      • Command Line (DAP CLI)
        • Getting Started
        • Secure Connection
        • Reference
          • dap snapshot
          • dap incremental
          • dap list
          • dap schema
          • dap initdb
          • dap syncdb
          • dap dropdb
      • Client Library
        • Examples
        • Reference
      • Release Notes
      • Status
    • DataSync
      • Interop API
      • Interop Data API
      • Grades Exchange API
      • OneRoster API
      • Platform API
    • Instructure Media
      • API Reference
        • Captions
        • Collection
        • Courses
        • Group
        • Insights
        • Media
        • Media Upload
        • Ping
        • Professional Captioning
        • Tags
        • Transfer Media
        • User
    • Quizzes
      • Quiz API
Powered by GitBook

Copyright © 2008-2024 Instructure, Inc. All rights reserved. Various trademarks held by their respective owners.

On this page
  • Regional Environments
  • Authentication
  • Obtaining a Token
  • Authenticating requests with an OAuth2 Bearer token
  • Issuer API
  • Create Issuer
  • Define BadgeClass
  • Issue Assertion

Was this helpful?

  1. Services
  2. Credentials

Getting Started

Here are some guided examples through which you can learn how to use the Canvas Credentials 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 Canvas Credentials API. See full Canvas Credentials API Docs for a list of endpoints and other pages of this documentation to get more detailed instructions.

Regional Environments

We support servers in various regions as well as a test server. The UI domain and API domain vary based on which server you are using. Please review the domains for Canvas Credentials environments around the globe. We use the US domain as a default in our documentation so be sure to substitute the proper domain if you are not using the US production servers.

Authentication

Canvas Credentials uses OAuth2 for most operations. As an API client user, you may obtain an OAuth2 Bearer Token on behalf of your own Canvas Credentials 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 in the Developers: Build an app that integrates with the Canvas Credentials API section.

Obtaining a Token

This guide will focus on getting started quickly, so we’ll use a password-based grant on Canvas Credentials’s US-based hosted service. Request authentication by making a POST request to https://api.badgr.io/o/token with your email address and password.

For example, with 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"
}

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).

For example, in a request to retrieve the user’s own profile using cURL, this header would be set like:

curl 'https://api.badgr.io/v2/users/self' -H "Authorization: Bearer YOURACCESSTOKEN"

Issuer API

Some of the most important API calls that clients make against the Canvas Credentials 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 Canvas Credentials API makes it easy. Every badge is awarded by an Issuer, so we’ll start by creating an Issuer, 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

Request Path: /v2/issuers

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 Canvas Credentials account. Get /v2/users/self to retrieve your profile and see your verified email addresses.

  • organizationId is the ID of your existing organization under which your issuer will be created.

Define 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/or criteriaUrl (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, string

    • targetUrl required, fully-qualified URL string

    • targetDescription optional, string

    • targetFramework 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 the targetUrl would be otherwise ambiguous.)

Issue Assertion

Request Path: /v2/badgeclasses/:badgeclass_id/assertions

Properties:

  • recipient is required, (the only required property) and it must be a JSON object with at least an identity key. Other optional properties of the recipient “IdentityObject” include: type (what type of identifier is identity? Choose between email, telephone, and url); and hashed (boolean, should the identity 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 original identity value was in case it is obscured behind the public-facing hash (when hashed == true).

  • recipient is required, (the only required property) and it must be a JSON object with the following properties:

    • type determines what type of identifier is identity, choose between email (default), telephone, and url)

    • identity is the value of the recipient identifier, for example an email address

    • hashed (boolean, should the identity 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 original identity value was in case it is obscured behind the public-facing hash (when hashed == 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 a narrative and/or an id (which is a URL to a piece of evidence hosted on HTTP)

  • issuedOn is optional: you may override the issue date with a date in the past. Expects an ISO8601 formatted 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 as issuedOn.

PreviousCredentialsNextAuthentication

Last updated 1 month ago

Was this helpful?

An Issuer Profile describes an entity that awards Open Badges. It is published as the Open Badges class.

Request Path: /v2/issuers/:issuer_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:

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:

Profile (Issuer)
BadgeClass
Assertion