Open Badges Version 2.1

Open Badges Specification

IMS Candidate Final
Version 2.1
IMS Candidate Final
Date Issued: January 24, 2020
Status: This document is for review and adoption by the IMS membership.
This version: https://www.imsglobal.org/spec/ob/v2p1/
Latest version: https://www.imsglobal.org/spec/ob/latest/
Errata: https://www.imsglobal.org/spec/ob/v2p1/errata/

IPR and Distribution Notice

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

The following participating organizations have made explicit license commitments to this specification:

Spec version Org name Date election made Necessary claims Type
2.1 Concentric Sky October 24, 2019 No RF RAND (Required & Optional Elements)
2.1 Digital Knowledge October 11, 2019 No RF RAND (Required & Optional Elements)
2.1 Washington State Board for Community and Technical Colleges (WSBCTC) October 4, 2019 No RF RAND (Required & Optional Elements)
2.1 Credly October 3, 2019 No RF RAND (Required & Optional Elements)

Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/speclicense.html.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

The limited permissions granted above are perpetual and will not be revoked by IMS or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

Public contributions, comments and questions can be posted here: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources.

© 2020 IMS Global Learning Consortium, Inc. All Rights Reserved.

Trademark information: http://www.imsglobal.org/copyright.html

Abstract

Open Badges are visual symbols of accomplishments packed with verifiable metadata according to the Open Badges specification. The Open Badges specification defines the properties necessary to define an achievement and award it to a recipient, as well as procedures for verifying badge authenticity and “baking” badge information into portable image files. It includes term definitions for representations of data in Open Badges. These term definitions appear in the current Open Badges JSON-LD Context File.

1. Introduction

1.1 Design Goals and Rationale

This section is non-normative.

Open Badges 2.1 is a specification that adds the Badge Connect™ API to Open Badges that allows badge recipients to easily move their Assertions between platforms to streamline the experience of earning and using Open Badges. The initial scope for this specification will cover Assertions and Profiles, with potential additions in future versions of other types of data held by applications in the various Open Badges ecosystem roles of Issuer, Displayer, and Host.

1.2 Use cases

This section is non-normative.

The following use cases are supported by this specification:

A recipient of an Assertion wants to import historically-issued badges into a chosen Host from an Issuer platform.
A user wishes to authorize an Issuer to push awarded Assertions to their chosen Host upon issue.
A user wishes to connect their Assertions to a recruiting platform.
A user wishes to move their badges from one Host to another Host.
A Relying Party wishes to obtain plaintext recipient identifier, to clearly understand the recipient profile in their badges.
An Issuer platform wishes to register a new recipient identifier on a recipient profile to which it would award badges.

1.3 Conformance and Certification

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words "MAY", "MUST", "MUST NOT", "OPTIONAL", "RECOMMENDED", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", and "SHOULD NOT" in this document are to be interpreted as described in [RFC2119].

An implementation of this specification that fails to implement a MUST/REQUIRED/SHALL requirement or fails to abide by a MUST NOT/SHALL NOT prohibition is considered nonconformant. SHOULD/SHOULD NOT/RECOMMENDED statements constitute a best practice. Ignoring a best practice does not violate conformance but a decision to disregard such guidance should be carefully considered. MAY/OPTIONAL statements indicate that implementers are entirely free to choose whether or not to implement the option.

The Conformance and Certification Guide for this specification may introduce greater normative constraints than those defined here for specific service or implementation categories.

1.4 Specification Documents

The full set of documents is comprised of the following documents:

1.5 Terminology

The following terms are used throughout this document.

  • Assertion: A representation of an awarded badge, used to share information about a badge belonging to one recipient.
  • Backpack: A term originally used to describe Open Badges services that provide importing, aggregation, and hosting features for recipients. These services match most closely with the role we now define as an Open Badge “Host” application. May also refer to the Mozilla Backpack.
  • BadgeClass: A collection of information about the accomplishment recognized by the Open Badge. Many assertions may be created corresponding to one BadgeClass.
  • Badge Connect™ API: Name of the RESTful web service for transfering assertions and profiles between systems.
  • Badge Issuer: A service that allows for the creation of BadgeClasses and the subsequent issuing of Assertions to recipients that conform to the Open Badges specification. Beginning with Open Badges 2.0, the candidate platform must issue a valid baked badge and demonstrate how the badge is retrieved by the recipient.
  • Badge Displayer: An application that displays verified badges to viewers. Beginning with Open Badges 2.0, the candidate platform must display a minimum set of badge metadata and support viewer-initiated verification of a badge.
  • Badge Host: An application that can import, aggregate, and publicly host Assertions for recipients. It also supports export of badges at user request. Beginning with Open Badges 2.0, the candidate platform must be able to import all formats of Open Badges as well as prove that badge metadata is not lost upon export of the badge.
  • Baked badge: Badge Assertions may be “baked” into image files as portable credentials.
  • Candidate platform: A platform implementing the Open Badges specification with the intent to obtain certification from IMS. They may be in the process to obtain certification.
  • Criteria: Detailed information about what must be done in order to be recognized with an assertion of a particular BadgeClass. Potential recipients may use criteria to understand what they must do; consumers may use criteria to understand what recipients did in order to earn the badge.
  • Evidence: Links to and descriptions of evidence related to the issuance of an Assertion, such as portfolio items or narratives that describe a badge recipient's work.
  • Extensions: Extensions are a means for issuers to add additional functionality through the use of metadata on Badge Objects beyond what the standard specifies itself.
  • Validation and verification (of badge assertions): Data validation is a procedure that ensures a cluster of data objects that form an Open Badge are appropriately formatted, published, and linked and that each data object conforms to requirements for its class. Validation of all data class instances used in an Open Badge is a part of badge verification. Verification is the process of ensuring the data that makes up an Open Badge is correct. It includes a number of data validation checks as well as procedures to ensure the badge is trustworthy. Verification is distinct from compliance certification for applications and services that implement the specification, though verification is typically a component of certification programs. See Verification in the current specification.

2. API

Badge Connect™ defines a JSON API protocol to be implemented by applications serving in the roles of Host and Relying Party. Typically Relying Parties SHOULD be certified Open Badges services in the Open Badges roles of Displayer or Issuer, though Hosts may also be relying parties to serve the Host to Host transfer use case. Badge Connect™ API uses OAuth 2.0 for authentication, granular resource-based permission scopes, and offers a number of required endpoints that MUST be implemented by Hosts and Relying Parties or both.

2.1 Architecture

Figure 1 Architecture

There are five key components to the Badge Connect™ API architecture.

Resource Owner
This is the user that owns the resources (badges) that are on the Host.
Web Browser
This is the web browser application that the user interacts with.
Relying Party
This is the web application that interacts with the Host on behalf of the resource owner. This component is called the Consumer in the IMS Security Framework [SEC-10].
Authorization Server
This is a server that implements the OAuth 2.0 endpoints on behalf of the Host. In many systems, the Authorization Server and the Host are combined.
Host
This is the resource server that has the protected resources (badges). This component is called the Provider in the IMS Security Framework [SEC-10].

The role of each component during Registration, Obtaining Tokens, and Authenticating with Tokens are described below.

2.2 Authentication

A Relying Party requests a token scoped for access to Open Badges Assertions on a Host that belong to a user (resource owner) of that Host service, using an OAuth 2.0 Authorization Code Grant as described in Section 4.2 of the IMS Security Framework [SEC-10]. Once a Relying Party obtains a code, it exchanges the code for an access token and optionally a refresh token. Subsequent API requests are authenticated with the access token until its expiration. If the Host previously provided a refresh token, the access token can be renewed.

2.2.1 Registration

The user starts on the Relying Party application and is offered the chance to connect that application to their chosen Host. The user supplies the Relying Party with the Host domain authority or selects their Host from a list.

When presented with a new target Host by which the Relying Party is attempting to gain an access token from, it MUST register itself with the Host and receive client credentials in order to proceed with the OAuth 2.0 token exchange. The Relying Party and Host MUST implement [RFC7591].

If the Relying Party does not know the Host's registration URL, it MUST request the Manifest as shown this sequence diagram:

Figure 2 Dynamic Client Registration Sequence Diagram

The registration request MUST use HTTPS (TLS 1.2 or 1.3). An example registration request may look like:

POST /o/register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: badge-host.example.com

{ "client_name": "Badge Issuer", "client_uri": "https://issuer.example.com", "logo_uri": "https://issuer.example.com/logo.png", "tos_uri": "https://issuer.example.com/terms-of-service", "policy_uri": "https://issuer.example.com/privacy-policy", "software_id": "13dcdc83-fc0d-4c8d-9159-6461da297388", "software_version": "54dfc83-fc0d-4c8d-9159-6461da297388", "redirect_uris": [ "https://issuer.example.com/o/redirect" ], "token_endpoint_auth_method": "client_secret_basic", "grant_types": [ "authorization_code", "refresh_token" ], "response_types": [ "code" ], "scope": "YOUR_REQUESTED_SPACE_SEPARATED_LIST_OF_SCOPES" }

The properties of the JSON body MUST be implemented as described in the following table. All URLs MUST use HTTPS (e.g. https://example.com/logo.png) and all URLs MUST have the same hostname. All required properties MUST be present in the registration request in order for it to be accepted by the Host.

Name Required Description
client_name Yes The human-readable name of the Relying Party.
client_uri Yes A page that which describes the Relying Party.
logo_uri Yes The logo of the Relying Party. The logo image uri should resolve to an image file with a square aspect ratio in either PNG or SVG format. Recommended resolution: 512x512px.
tos_uri Yes The Terms of Service of the Relying Party.
policy_uri Yes The Privacy Policy of the Relying Party.
software_id Yes A unique idenfitier assigned by the client developer. As described in [RFC7591], it SHOULD remain the same for all instances of the client software.
software_version Yes A version identifier string for the client software. The value SHOULD change on any update to the client software.
redirect_uris Yes Array of redirection URI strings for use in the OAuth 2.0 flow.
token_endpoint_auth_method No String indicator of the requested authentication method for the token endpoint. In this specification only "client_secret_basic" is allowed:
  • "client_secret_basic": The relying party uses the HTTP Basic authentication method as defined in OAuth 2.0.
If omitted, the default is "client_secret_basic".
grant_types No Array of OAuth 2.0 grant type strings. In this specification only "authorization_code" and refresh_token" are allowed:
  • "authorization_code": The authorization code grant type defined in OAuth 2.0.
  • "refresh_token": The refresh token grant type defined in OAuth 2.0.
If omitted, the default behavior is that the client will use only the "authorization_code" grant type.
response_types No Array of OAuth 2.0 response type strings. In this specification only "code" is allowed:
  • "code": The authorization code response type defined in OAuth 2.0.
If omitted, the default is that the client will use only the "code" response type.
scope No String containing a space-separated list of scope values that this client is permitted to use when requesting access tokens. Scopes are defined in Scopes. If omitted, the Host MAY register a client with a default set of scopes.

If the Host accepts the registration request, it will store the information provided in the request and generate a set of client credentials for the Relying Party to use when requesting access tokens.

All the information provided by the Relying Party MUST be returned to the Relying Party, including modifications to the properties as the Host deems necessary.

HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{ "client_id": "BADGECONNECT_s6BhdRkqt3", "client_secret": "czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3", "client_id_issued_at": 1558280111, "client_secret_expires_at": 1558290111, "client_name": "Badge Issuer", "client_uri": "https://issuer.example.com", "logo_uri": "https://issuer.example.com/logo.png", "tos_uri": "https://issuer.example.com/terms-of-service", "policy_uri": "https://issuer.example.com/privacy-policy", "software_id": "13dcdc83-fc0d-4c8d-9159-6461da297388", "software_version": "54dfc83-fc0d-4c8d-9159-6461da297388", "redirect_uris": [ "https://issuer.example.com/o/redirect" ], "token_endpoint_auth_method": "client_secret_basic", "grant_types": [ "authorization_code", "refresh_token" ], "response_types": [ "code" ], "scope": "YOUR_REQUESTED_SPACE_SEPARATED_LIST_OF_SCOPES" }

The following table describes the properties present in the client registration response that were not included in the request. These are all REQUIRED properties.

Name Description
client_id REQUIRED. An OAuth 2.0 client identifier string. The value SHOULD NOT be currently valid for any other registered client.
client_secret REQUIRED. An OAuth 2.0 client secret string.
client_id_issued_at REQUIRED. The time at which the client_id was issued.
client_secret_expires_at REQUIRED. The time at which the client_secret will expire. MAY be 0 for no expiration.

2.2.2 Obtaining Tokens

After the Relying Party is registered with the Host as described in Registration, the Relying Party then MAY initiate an authorization request as described in Section 4.2 of the IMS Security Framework [SEC-10] by redirecting the user to the Host's authorizationUrl as declared in the Host's Badge Connect™ Manifest.

Figure 3 Authorization Sequence Diagram

All required properties must be included in the authorization request.

Name Required Description
response_type Yes Value MUST be set to "code".
client_id Yes The client identifier. MUST be client_id provided in the Registration response.
redirect_uri Yes The relying party's redirection endpoint. MUST match one of the redirect_uris in the Registration request. Although this is optional in the IMS Security Framework [SEC-10], it is REQUIRED by this specification.
scope Yes The scope of the authorization request. This is a space delimited list of scopes.
state Yes An opaque value used by the client to maintain state between the request and callback.
code_challenge Yes This is BASE64URL-ENCODE(SHA256(ASCII(code_verifier))).
code_challenge_method Yes This MUST have a value of S256 i.e. the SHA256 code verifier transformation method is used.

An example authorization request (line breaks for display purposes only):

GET /authorize?
response_type=code
&client_id=BADGECONNECT_s6BhdRkqt3
&state=xyzjklabc
&scope=SPACE_SEPARATED_STRING_OF_REQUESTED_SCOPES
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challange_method=S256
&redirect_uri=https%3A%2F%2Fbadgehost.example.com%2Fo%2Fredirect HTTP/1.1
Host: www.example.com

If the Host does not recognize the Relying Party's redirection endpoint from a prior connection with this Relying Party, the Host SHOULD throw an error specifying that the redirection endpoint is not applicable to any registered client and registration should be made before proceeding. If the redirect_uri matches the known client_id, the Host MAY honor the request to present the user or resource owner with the option to authorize the request. If the Host recognizes the Relying Party, the Host MAY skip the need to register the client again. If the user authorizes the Relying Party to access their resources with the requested scopes, the Host MUST redirect the user back to the redirect_uri with a code query string parameter.

With the supplied code, the Relying Party SHOULD attempt to exchange the code for a token. The Relying Party makes an authorization grant POST request to the Host's tokenUrl, as declared in the Host's Badge Connect™ Manifest. The HTTP POST request MUST include a Basic authorization header with the client_id and client_secret provided by the response to the registrationUrl endpoint. The body of the request MUST include the following form fields:

Name Required Description
grant_type Yes Value MUST be set to "authorization_code".
code Yes The authorization code received from the authorization server.
redirect_uri Yes The relying party's redirection endpoint.
scope Yes The scope of the access request.
code_verifier Yes The PKCE code verifier.

An example token request:

POST /badge/connect/auth/token HTTP/1.1
Host: www.example.com
Authorization: Basic QkFER0VDT05ORUNUX3M2QmhkUmtxdDM6Y3paQ2FHUlNhM0YwTXpvM1JtcG1jREJhUW5JeFMzUkVVbUp1Wmxaa2JVbDM=
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code &code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4 &redirect_uri=https://badgehost.example.com/o/redirect &scope=SPACE_SEPARATED_STRING_OF_REQUESTED_SCOPES &code_verifier=YOUR_GENERATED_CODE_VERIFIER

If the authorization server finds the request to be a valid, it generates and returns an access token and optionally a refresh token.

If the request fails, the Host SHOULD return a response as described in RFC6749.

2.2.3 Authenticating with Tokens

After obtaining a token using the method above, a Relying Party MAY request resources controlled by the resource owner from Host endpoints using the token in the HTTP Authorization header. An example follows, where 2YotnFZFEjr1zCsicMWpAA is the token:

Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Figure 4 Access Protected Resource Sequence Diagram

2.2.4 Revocation by Resource Owner

Host platforms MUST provide a list of authorized clients to the resource owner for review. The list SHOULD identify the relying party and when the grant was created. From this list the resource owner MUST be able to revoke the relying party's access.

Subsequent attempts to use the relevant revoked access or refresh tokens SHOULD result in a 401 UNAUTHENTICATED error.

2.2.5 Revocation by Relying Party

Host platforms MAY provide a mechanism to revoke both types of tokens by providing a token revocation endpoint in their manifest file [RFC7009]. This revocation endpoint allows a Relying Party to invalidate its tokens if the end-user logs out, changes identity, or removes the respective Host.

If token revocation endpoints are implemented they MUST support the revocation of refresh tokens and SHOULD support the revocation of access tokens.

Revocation by Relying Party is not part of the IMS Security Framework [SEC-10]. If the implementer decides to implement it, they SHOULD follow [RFC7009].

Revocation Request

The Relying Party makes a POST request to the Host's token revocation URL, as declared in the Host's Badge Connect™ Manifest. The HTTP request entity-body MUST contain a token parameter containing the refresh token or access token.

Relying Parties MAY also pass a token_type_hint parameter with a value of access_token or refresh_token.

An example revocation request:

POST /badge/connect/auth/revoke_token HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

token=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4 &token_type_hint=access_token

2.3 Scopes

Access to resources in the Badge Connect™ API require an access token. These access tokens have a permissioned scope when they are created and inform the responding application which resources the entity has access to.

Name Description
https://purl.imsglobal.org/spec/ob/v2p1/scope/assertion.readonly Permission to read assertions for the authenticated entity.
https://purl.imsglobal.org/spec/ob/v2p1/scope/assertion.create Permission to create assertions for the authenticated entity.
https://purl.imsglobal.org/spec/ob/v2p1/scope/profile.readonly Permission to read the profile for the authenticated entity.
https://purl.imsglobal.org/spec/ob/v2p1/scope/profile.update Permission to update the profile for the authenticated entity.
offline_access Permission to issue a refresh_token along with the access_token.

2.4 Manifest

All Hosts MUST implement a JSON manifest file which contains configuration information about their implementation, such as scope support, redirect URIs, and branding information.

Hosts MUST serve the manifest at the well-known path /.well-known/badgeconnect.json on the relevant service domain compliant with [RFC5785]. The manifest MUST be provided over secure TLS 1.2 or 1.3 protocol e.g. https://YOUR_DOMAIN/.well-known/badgeconnect.json.

2.4.1 Requesting Manifests

Upon requesting a Manifest file from a Host, the requester SHOULD respect the Cache-Control and Expires headers if present in the response and configure local cache to match the directives it declares. If directives include one of no-cache, no-store, the requester SHOULD NOT cache the data for future interactions. If directives include max-age or if an Expires header is present, the requester SHOULD cache the manifest file data, if valid, up to the expiration indicated, either at the time indicated by the Expires header or max-age seconds from request time.

An Etag header MAY be offered with the Manifest file response. If so, after a resource's declared expiration, a requester MAY include an If-None-Match header containing the value of the Etag to check if the resource is still fresh. If so the server may return a 304 Not Modified response status code, and a new Expires or Cache-Control header MAY be included, which the requester SHOULD use to update the cache expiration.

2.4.2 Manifest Structure

{
  "@context": "https://purl.imsglobal.org/spec/ob/v2p1/ob_v2p1.jsonld",
  "id": "https://badgehost.example.com/.well-known/badgeconnect.json",
  "badgeConnectAPI": [{
    "name": "A Badge Host",
    "image": "https://badgehost.example.com/logo.png",
    "apiBase": "https://badgehost.example.com/api/obc/v1",
    "version": "v1p0",
    "termsOfServiceUrl": "https://badgehost.example.com/terms",
    "privacyPolicyUrl": "https://badgehost.example.com/privacy",
    "scopesOffered": [
      "https://purl.imsglobal.org/spec/ob/v2p1/scope/assertion.readonly",
      "https://purl.imsglobal.org/spec/ob/v2p1/scope/assertion.create",
      "https://purl.imsglobal.org/spec/ob/v2p1/scope/profile.readonly",
      "https://purl.imsglobal.org/spec/ob/v2p1/scope/profile.update"
    ],
    "registrationUrl": "https://badgehost.example.com/o/register",
    "authorizationUrl": "https://badgehost.example.com/o/auth",
    "tokenUrl": "https://badgehost.example.com/o/token",
    "tokenRevocationUrl": "https://badgehost.example.com/o/revoke_token"
  }]
}

2.4.3 Manifest Properties

Property Required Description
name Yes The name of the platform supporting the API. This SHOULD reflect the user-facing identity of the platform requesting authorization.
image No An image representing the platform. May be a URI to a hosted image or a Data URI. The logo image uri should resolve to an image file with a square aspect ratio in either PNG or SVG format. Recommended resolution: 512x512px.
apiBase Yes Fully qualified URL that will be concatenated with the API endpoints. It SHOULD NOT have a trailing slash "/".
E.g. apiBase + "/assertions"
version Yes A string representing the implemented version. MUST be in the format of vMAJORpMINOR where MAJOR and MINOR are integers.
termsOfServiceUrl Yes Fully qualified URL to the platform's terms of service. Other platforms SHOULD link to this resource as part of their authorization interface.
privacyPolicyUrl Yes Fully qualified URL to the platform's privacy policy. Other platforms SHOULD link to this resource as part of their authorization interface.
scopesOffered Yes An array of strings listing the scopes supported by the Host in the form of fully qualified URLs to the scope descriptors.
registrationUrl Yes A fully qualified URL to which the Relying Party would make the client registration request to before performing the authorization flow.
authorizationUrl Yes A fully qualified URL to the host's authorization endpoint.
tokenUrl Yes A fully qualified URL to the host's token request endpoint for exchanging an authorization code for a bearer token.
tokenRevocationUrl No A fully qualified URL to the host's token revocation endpoint for invalidating an existing refresh token or access token. When this property is omitted or has a null value, it will be assumed that the Host does not support token revocation by a Relying Party.

2.5 Response Envelope

Responses from all Badge Connect-specific APIs in this document are wrapped in a JSON envelope. All response envelopes have a status property and one or more result properties. The result property name(s) and data types are defined in the Responses section for each endpoint.

Responses related to standarized OAuth requests should use the prescribed format in their respective RFC.

2.5.1 Status

The "status" property MUST appear on all responses.

Name Description
error A nullable string and the human-readable message describing the problem.
statusCode The HTTP status code of the response.
statusText A string matching one of the enumerated and allowed values for the given endpoint.

2.5.2 Pagination

Pagination of results is controlled by two query string parameters appended to the request.

  • limit - the number of results to return
  • offset - the index of the first record to return (zero indexed)

The HTTP Link header MUST appear when a list response is incomplete and MAY appear for complete responses.

It is RECOMMENDED that Host implementations pass the total result count back to the requester. When the total result count is not known, this MUST be omitted. The value MUST be provided in the custom HTTP header: X-Total-Count.

The header MUST support all of the following link relations (rel values):

Name Description
next The link relation for the immediate next page of results. This MUST appear when the current list response is incomplete.
last The link relation for the last page of results. This MUST always appear.
first The link relation for the first page of results. This MUST always appear.
prev The link relation for the immediate previous page of results. This MUST appear when the offset is greater than zero.

An example of Link header pagination, line breaks added for readability:

Link:
<https://host.example.com/v1/assertions?limit=10&offset=20>; rel="next",
<https://host.example.com/v1/assertions?limit=3&offset=500>; rel="last",
<https://host.example.com/v1/assertions?limit=10&offset=0>; rel="first",
<https://host.example.com/v1/assertions?limit=10&offset=0>; rel="prev"

2.6 Assertion Payload

An Assertion Payload contains either a signed or unsigned Assertion. If both are specified, the unsigned Assertion MUST be ignored. Null values MAY be omitted.

Three examples:

{
  "assertion": { ... },
  "signedAssertion": null
}



{
  "assertion": null,
  "signedAssertion": "abced..."
}




{
  "assertion": { ... }
}
Property Expected Type Required Description
assertion Assertion No An unsigned Assertion object in serialized JSON-LD.
signedAssertion String No A signed Assertion in JWS Compact JWS Serialization format.

2.7 Endpoints

2.7.1 Assertions

GET /assertions
Description Fetch Assertions for the supplied parameters and authentication token. The response envelope contains a list of zero or more matching signed Assertions and a list of zero or more matching unsigned assertions. There SHOULD be only one assertion (signed or unsigned) for any particular assertion ID as the IDs are intended to be globally unique. The Host SHOULD return Assertions (signed and unsigned) ordered by last update, descending and SHOULD return only Assertions (signed and unsigned) updated after the timestamp requested if supplied.
Query Parameters
Name Type Description
limit Integer Indicate how many results should be retrieved in a single page.
offset Integer Indicate the index of the first record to return (zero indexed).
since An ISO 8601 compatible timestamp with a time zone indicator. Retrieve Assertions that were created or updated after the provided timestamp.
Responses
Name Type Description
200 Assertions Response This is the response when the request has been completed successfully.
400 400 Response An invalid request was made.
401 401 Response The request was not correctly authorized.
404 404 Response The requested resource does not exist.
405 405 Response This method is not allowed on the endpoint.
500 - This code should be used only if there is catastrophic error.
POST /assertions
Description Create or update an Assertion. The posted data MUST be an Assertion Payload.
Responses
Name Type Description
200 Assertion Response This is the response when the request has been completed successfully.
400 400 Response An invalid request was made.
401 401 Response The request was not correctly authorized.
404 404 Response The requested resource does not exist.
405 405 Response This method is not allowed on the endpoint.
500 - This code should be used only if there is catastrophic error.

2.7.2 Profile

GET /profile
Description Fetch the profile for the supplied authentication token. For a successful result, the Host MUST return a valid OB Profile instance.
Responses
Name Type Description
200 Profile Response This is the response when the request has been completed successfully.
400 400 Response An invalid request was made.
401 401 Response The request was not correctly authorized.
404 404 Response The requested resource does not exist.
405 405 Response This method is not allowed on the endpoint.
500 - This code should be used only if there is catastrophic error.
POST /profile
Description Update the profile for the authenticate entity. The request SHOULD only include profile identifier properties to be added to the profile, not any existing data. Successful request responses will be the same as GET Profile and may not include the patched values (as the Host may be waiting for asynchronous processes to complete before accepting the value). The value may never become part of the published profile. A Host MAY respond with 400 BAD_REQUEST to reject data that is known immediately to not be acceptable by the platform, e.g. to reject a "telephone" property if the Host cannot validate telephone numbers.
Responses
Name Type Description
200 Profile Response This is the response when the request has been completed successfully.
400 400 Response An invalid request was made.
401 401 Response The request was not correctly authorized.
404 404 Response The requested resource does not exist.
405 405 Response This method is not allowed on the endpoint.
500 - This code should be used only if there is catastrophic error.

2.8 Retry Behavior

Receivers of requests MAY implement a Retry-After header to indicate a period of time to wait before attempting the request again.

If no Retry-After header is present and the response is non-2XX, it is recommended to retry the request in 30 minutes for an additional two attempts. After which, it MAY be desirable to alert the recipient that there is an issue with the connection (e.g. perhaps they need to reauthenticate or manually trigger the request when they believe services are back up).

2.9 Responses

2.9.1 200 GET Assertions Response

Property Required Description
status Yes The Status object describing the success or failure of the request.
assertions No The matching unsigned Assertions. The total number of unsigned and signed assertions should not exceed the pagination limit. Not required if there are no unsigned assertions.
signedAssertions No The matching signed Assertions in JWS Compact Serializion format. The total number of unsigned and signed assertions should not exceed the pagination limit. Not required if there are no signed assertions.
{
    "status": {
        "error": null,
        "statusCode": 200,
        "statusText": "OK"
    },
    "assertions": [
        {
          "@context": "https://w3id.org/openbadges/v2",
          "id": "https://issuer.example.com/api/v20/assertion/1234567",
          "type": "Assertion",
          ...
        }
    ],
    "signedAssertions": [
        "eyJhbGciOiJSUzI1NiJ9.ew0KICAiQGNvbnRleHQiOiAiaHR0cHM6Ly93M2lkLm9yZy9vcGVuYmFkZ2VzL3YyIiwNCiAgInR5cGUiOiAiQXNzZXJ0aW9uIiwNCiAgImlkIjogImh0dHBzOi8vZXhhbXBsZS5vcmcvYmV0aHMtcm9ib3RpY3MtYmFkZ2UuanNvbiIsDQogICJyZWNpcGllbnQiOiB7DQogICAgInR5cGUiOiAiZW1haWwiLA0KICAgICJoYXNoZWQiOiB0cnVlLA0KICAgICJzYWx0IjogImRlYWRzZWEiLA0KICAgICJpZGVudGl0eSI6ICJzaGEyNTYkYzdlZjg2NDA1YmE3MWI4NWFjZDhlMmU5NTE2NmM0YjExMTQ0ODA4OWYyZTE1OTlmNDJmZTFiYmE0NmU4NjVjNSINCiAgfSwNCiAgImltYWdlIjogImh0dHBzOi8vZXhhbXBsZS5vcmcvYmV0aHMtcm9ib3QtYmFkZ2UucG5nIiwNCiAgImV2aWRlbmNlIjogImh0dHBzOi8vZXhhbXBsZS5vcmcvYmV0aHMtcm9ib3Qtd29yay5odG1sIiwNCiAgImlzc3VlZE9uIjogIjIwMTYtMTItMzFUMjM6NTk6NTlaIiwNCiAgImJhZGdlIjogImh0dHBzOi8vZXhhbXBsZS5vcmcvcm9ib3RpY3MtYmFkZ2UuanNvbiIsDQogICJ2ZXJpZnkiOiB7DQogICAgInR5cGUiOiAiU2lnbmVkQmFkZ2UiLA0KICAgICJjcmVhdG9yIjogImh0dHBzOi8vZXhhbXBsZS5vcmcvcHVibGljS2V5Ig0KICB9DQp9.Liv4CLviFH20_6RciUWf-jrUvMAecxT4KZ_gLHAeT_chrsCvBEE1uwgtwiarIs9acFfMi0FJzrGye6mhdHf3Kjv_6P7BsG3RPkYgK6-5i9uZv4QAIlvfNclWAoWUt4j0_Kip2ftzzWwc5old01nJRtudZHxo5eGosSPlztGRE9G_g_cTj32tz3fG92E2azPmbt7026G91rq80Mi-9c4bZm2EgrcwNBjO0p1mbKYXLIAAkOMuJZ_8S4Go8S0Sg3xC6ZCn03zWuXCP6bdY_jJx2BpmvqC3H55xWIU8p5c9RxI8YifPMmJq8ZQhjld0pl-L8kHolJx7KGfTjQSegANUPg"
    ]
}

2.9.2 200 POST Assertion Response

Property Required Description
status Yes The Status object describing the success or failure of the request.
{
    "status": {
        "error": null,
        "statusCode": 200,
        "statusText": "OK"
    }
}

2.9.3 200 GET Profile Response

Property Required Description
status Yes The Status object describing the success or failure of the request.
profile Yes The matching Profile.
{
    "status": {
        "error": null,
        "statusCode": 200,
        "statusText": "OK"
    },

"profile": {
    "@context": "https://w3id.org/openbadges/v2",
    "id": "https://host.example.com/profile/12345",
    "type": "Profile",
    "name": "John Appleseed ",
    "url": "https://example.com",
    "email": "john@example.com"
}

}

2.9.4 200 POST Profile Response

Property Required Description
status Yes The Status object describing the success or failure of the request.
profile Yes The updated Profile.
{
    "status": {
        "error": null,
        "statusCode": 200,
        "statusText": "OK"
    },

"profile": {
    "@context": "https://w3id.org/openbadges/v2",
    "id": "https://host.example.com/profile/12345",
    "type": "Profile",
    "name": "John Appleseed ",
    "url": "https://example.com",
    "email": "john@example.com"
}

}

2.9.5 400 Response

{
    "status": {
        "error": "Additional information regarding the error in human readable format.",
        "statusCode": 400,
        "statusText": "BAD_REQUEST"
    }
}

Allowed values for the statusText property by endpoint:

  • POST /assertions
    • REQUEST_VALIDATION_ERROR (data validation of the request failed)
    • RECIPIENT_PROFILE_MISMATCH (profile match failed)
    • INVALID_BADGE (badge validation failed)
    • BAD_REQUEST (all other errors)
  • GET /assertions
    • REQUEST_VALIDATION_ERROR (data validation of the request failed)
    • BAD_REQUEST (all other errors)
  • POST /profile
    • REQUEST_VALIDATION_ERROR (data validation of the request failed)
    • BAD_REQUEST (all other errors)

2.9.6 401 Response

{
    "status": {
        "error": "Additional information regarding the error in human readable format.",
        "statusCode": 401,
        "statusText": "UNAUTHENTICATED"
    }
}

PERMISSION_DENIED is another acceptable value for statusText in the event that the request was authenticated but the scope does not include the requested resource.

2.9.7 404 Response

{
    "status": {
        "error": null,
        "statusCode": 404,
        "statusText": "NOT_FOUND"
    }
}

2.9.8 405 Response

{
    "status": {
        "error": "Additional information regarding the error in human readable format.",
        "statusCode": 405,
        "statusText": "METHOD_NOT_ALLOWED"
    }
}

A. Revision History

This section is non-normative.

A.1 Changes

A.2 Version History

Version No. Release Date Comments
Version 2.1 IMS Candidate Final January 24, 2020 Second coordinated release.
v2.1 Candidate Final August 29, 2019 First release of the Candidate Final specification

B. References

B.1 Normative references

[OB-21]
Open Badges Specification v2.1. Jeff Bohrer; Andy Miller. IMS Global. January 24, 2020. URL: https://www.imsglobal.com/spec/ob/v2p1/
[OB-CERT-21]
Open Badges Conformance and Certification Guide v2.1. Jeff Bohrer; Andy Miller. IMS Global. January 24, 2020. URL: https://www.imsglobal.org/spec/ob/v2p1/cert/
[OB-JSON-21]
JSON Schema Files for Open Badges Badge Connect(TM) API v2.1. Jeff Bohrer; Andy Miller. IMS Global. January 24, 2020. URL: https://purl.imsglobal.org/spec/ob/v2p1/schema/json/
[OB-JSONLD-21]
Open Badges JSON-LD Context File. Jeff Bohrer; Alex Hripak; Andy Miller; Nate Otto. IMS Global. January 24, 2020. URL: https://purl.imsglobal.org/spec/ob/v2p1/context/
[OB-OPEN-21]
OpenAPI 3.0 File for Open Badges Badge Connect(TM) API v2.1. Jeff Bohrer; Andy Miller. IMS Global. January 24, 2020. URL: https://purl.imsglobal.org/spec/ob/v2p1/schema/openapi/imsob_v2p1.yaml
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC5785]
Defining Well-Known Uniform Resource Identifiers (URIs). M. Nottingham; E. Hammer-Lahav. IETF. April 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5785
[RFC6749]
The OAuth 2.0 Authorization Framework. D. Hardt, Ed.. IETF. October 2012. Proposed Standard. URL: https://tools.ietf.org/html/rfc6749
[RFC7009]
OAuth 2.0 Token Revocation. T. Lodderstedt, Ed.; S. Dronia; M. Scurtescu. IETF. August 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc7009
[RFC7515]
JSON Web Signature (JWS). M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7515
[RFC7591]
OAuth 2.0 Dynamic Client Registration Protocol. J. Richer, Ed.; M. Jones; J. Bradley; M. Machulak; P. Hunt. IETF. July 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7591
[SEC-10]
IMS Global Security Framework v1.0. C. Smythe; C. Vervoort; M. McKell; N. Mills. IMS Global Learning Consortium. April 2019. IMS Final Release. URL: https://www.imsglobal.org/spec/security/v1p0/

C. List of Contributors

The following individuals contributed to the development of this document:

Name Organization Role
Alexander HripakCredlyEditor
Sara ArjonaMoodle
Jeff BohrerIMS Global
Viktor HaagD2L
Takahiro HataDigital Knowledge EdTech Lab
Chris HoustoneLumen
Mark LeubaIMS Global
Andy MillerIMS Global
Omid MufeedDigitalme
Nate OttoConcentric Sky
Justin PitcherCampus Labs
Alex ReisD2L

IMS Global Learning Consortium, Inc. ("IMS Global") is publishing the information contained in this document ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.

IMS Global makes no warranty or representation regarding the accuracy or completeness of the Specification.

This material is provided on an "As Is" and "As Available" basis.

The Specification is at all times subject to change and revision without notice.

It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.

IMS Global would appreciate receiving your comments and suggestions.

Please contact IMS Global through our website at http://www.imsglobal.org.

Please refer to Document Name: Open Badges Specification 2.1

Date: January 24, 2020