Consumers of the OB / CLR API must acquire an OAuth 2.0 access token from an authorization server for making API calls. The acquisition of the token implies a set of steps:

Call the ServiceDescription endpoint. Once you know the base url of your authorization server, make a GET call to the well-know getServiceDescription endpoint. The response will contains all the endpoints needed for register your client application (x-imssf-registrationUrl) and acquiring and access token (authorizationUrl, tokenUrl and refreshUrl) with the desired scopes.

GET /ims/ob/v3p0/discovery HTTP/1.1
Host: example.edu
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

...
"components": {
    "securitySchemes": {
        "OAuth2ACG": {
            "type": "oauth2",
            "description": "OAuth 2.0 Authorization Code Grant authorization",
            "x-imssf-name": "Example Provider",
            "x-imssf-privacyPolicyUrl": "provider.example.com/privacy",
            "x-imssf-registrationUrl": "provider.example.com/registration",
            "x-imssf-termsOfServiceUrl": "provider.example.com/terms",
            "flows": {
                "authorizationCode": {
                    "tokenUrl": "provider.example.com/token",
                    "authorizationUrl": "provider.example.com/authorize",
                    "refreshUrl": "provider.example.com/token",
                    "scopes": {
                        "https://purl.imsglobal.org/spec/clr/v2p0/scope/delete" : "...",
                        "https://purl.imsglobal.org/spec/clr/v2p0/scope/readonly" : "...",
                        "https://purl.imsglobal.org/spec/clr/v2p0/scope/replace" : "..."
                    }
                }
            }
        }
    },
    "schemas": {
        ...
    }
}
...

Register your client using OAuth 2.0 Dynamic Client Registration Protocol [RFC7591]. To do that, make a POST call to the endpoint defined in the x-imssf-registrationUrl field from the previous step.

POST /connect/register HTTP/1.1
Host: auth.1edtech.org
Accept: application/json
Content-Type: application/json; charset=utf-8

{
    "client_name": "Example Client Application",
    "client_uri": "https://client.1edtech.org/",
    "logo_uri": "https://client.1edtech.org/logo.png",
    "tos_uri": "https://client.1edtech.org/terms",
    "policy_uri": "https://client.1edtech.org/privacy",
    "software_id": "c88b6ed8-269e-448e-99be-7e2ff47167d1",
    "software_version": "v4.0.30319",
    "redirect_uris": [
        "https://client.1edtech.org/Authorize"
    ],
    "token_endpoint_auth_method": "client_secret_basic",
    "grant_types": [
        "authorization_code",
        "refresh_token"
    ],
    "response_types": [
        "code"
    ],
    "scope": "https://purl.imsglobal.org/spec/ob/v3p0/scope/delete https://purl.imsglobal.org/spec/ob/v3p0/scope/assertion.readonly https://purl.imsglobal.org/spec/ob/v3p0/scope/replace offline_access"
}

The response object will contain the details needed to perform the OAuth 2.0 Authorization Code Grant flow (client_id, client_secret, among others).

Acquire an access token following OAuth 2.0 Authorization Code Grant flow as described in then IMS Security Framework [SEC-11]. Briefly, it consists in building the authorizationUrl from the url defined in the authorizationUrl field gotten from step one with some query parameters. The use of Proof Key for Code Exchange (PKCE) [RFC7636] is recommended.

Once built, redirect the user to this url in order to start the OAuth 2.0 Authorization Code Grant flow.

HTTP/1.1 302 Found
Location: https://auth.1edtech.org/authorize?
client_id=4ad36680810420ed
&response_type=code
&scope=https%3A%2F%2Fpurl.imsglobal.org%2Fspec%ob%2Fv3p0%2Fscope%2Fassertion.readonly%20offline_access
&redirect_uri=https%3A%2F%client.1edtech.org%2FAuthorize
&state=26357667-94df-4a14-bcb1-f55449ddd98d
&code_challenge=XeDw66i9FLjn7XaecT_xaFyUWWfUub02Kw118n-jbEs
&code_challenge_method=S256

Once the authorization is made, the authorization server will redirect the browser back to the specified redirect_uri with the code, scope, and state query string parameters.

Then, you have to acquire an access token by making a POST request to the tokenUrl gotten from the Service Description endpoint. The HTTP POST request MUST include a Basic authorization header with the client_id and client_secret provided in the registration response. The body of the token request MUST include the following form fields: grant_type, code, redirect_uri, scope and code_verifier.

POST /token HTTP/1.1
Host: auth.1edtech.org
Authorization: Basic NDE2ZjI1YjhjMWQ5OThlODoxNWQ5MDA4NTk2NDdkZDlm
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
    &code=7c7a73263ee14b2b48073d0615f286ec74f6636689046cb8dbede0b5e87a1338
    &redirect_uri=https%3A%2F%client.1edtech.org%2FAuthorize
    &scope=https%3A%2F%2Fpurl.imsglobal.org%2Fspec%2Fob%2Fv3p0%2Fscope%2Fassertion.readonly+offline_access
    &code_verifier=mYUQfKNgI1lSbY8EqtvNHLPzu0x%2FcVKO3fpWnX4VE5I%3D

The response of this call will contain the access token to use in future calls to the API.

HTTP/1.1 200 OK
Cache-Control: no-store, no-cache, max-age=0
Pragma: no-cache
Content-Type: application/json; charset=UTF-8

{
    "access_token": "863DF0B10F5D432EB2933C2A37CD3135A7BB7B07A68F65D92",
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "https://purl.imsglobal.org/spec/ob/v3p0/scope/assertion.readonly offline_access"
}

Here are a selection of user stories covering how to add on support for the OB 3.0 API as an Issuer to a simple product after completing the issuer quickstart above. Completing the consumer-side portion of the will potentially qualify a product for conformance certification as an Open Badges Issuer (with API service-consumer-write support). This is a presentation of the experience of using the API from the user's perspective. Additional under-the-hood technical details for each procedure are described in the Specification section 6: Open Badges API.

As a badge holder, I can inform my issuer of my selected Open Badges host service.

Provide the base url or domain of the selected Open Badges host service to the issuer. This could utilize a text input where a user can paste a URL, or a consumer service could add known service providers to a list, presenting the manual input as an advanced option.

As an issuer service, I can discover information about an Open Badges host service.

The service consumer will call the getServiceDescription endpoint from the base url of the Open Badges service provider (host).

As an issuer service, I can register with a Open Badges host service provider.

By performing the OAuth 2.0 Client Dynamic Registration [RFC7591] to the endpoint defined in the x-imssf-registrationUrl field of the Open Badges Host service description.

As a badge holder, I can request and approve a connection between my issuer and my host account.

By following the OAuth 2.0 Authorization Code Grant flow in their browser, following redirects between the issuer and the host service.

As a badge holder, I can select one, some or all OpenBadgeCredentials to transmit to my host account.

A basic service consumer (write) integration would typically push all awarded badges to the host, and a more advanced service consumer may enable users to select a specific scope of credentials for transmission.

As a badge holder, I can see that new badges I am awarded are automatically transmitted to my host, even when I am not interacting with either the issuer or host services directly, if I have configured my issuer to send badges automatically.

As a badge holder, I can deauthorize my issuer from connection to my Open Badges host, so my issuer can't retrieve badges from my Open Badges host no more.

By revoking the access token granted to the issuer from within the Open Badges (service provider) interface.

As a user who has revoked consumer access to my host, I should see the broken connection within the consumer app and be able to initiate reauthorization.

While authenticated with a host service, one action users may take is to view the connected issuer(s) or displayer(s) they have authorized and to revoke some of those approvals. When a user takes this action, it invalidates any access tokens or refresh tokens the connected services, so that those services may no longer access API endpoints on the user's behalf. This should be handled in the issuer or displayer service as a potential expected outcome, after which the service may display an inactive status on the connection and/or prompt the user to reauthorize if they desire to continue sending badges to that host once again.

Your issuer service may discover that your access credentials no longer work as expected when you receive a 401 or 403 status response from the host when attempting to access a protected endpoint and then subsequently receive an error response when attempting token refresh.

The above description of a consumer implementation shows the requests that are made of a provider. This guide does not go into depth about how to accomplish the provider side of these interactions, but the API roughly follows common OAuth patterns for (a) dynamic client registration, authorization code access token grants, and protected resource endpoint access.

• Provide the ServiceDescription endpoint with the right values for the OAuth2ACG's securitySchema. The urls there must point to your OAuth related endpoints.
• Allow Registration of clients using Dynamic Registration.
• Implement OAuth 2.0 Authorization Code Grant flow for granting tokens.
• Enable access to protected resources to requests authenticated with an appropriately scoped access token.
• Enable deauthorization of access tokens via user interface. Show a list of authorized applications and their associated access details and enable users to revoke authorizations from the service provider (host).

Both issuers and recipients (credential subjects) of Open Badges and CLR credentials may be identified with a range of identifiers.

Issuers may be identified with an HTTP URL that resolves to an issuer profile that expresses profile and key information in JSON-LD. Or, they might be identified by a Decentralized Identifier (DID) that resolves to a document with some information about the issuer and/or its signing key(s).

DID methods most commonly used in interoperability testing by community members, both for issuer identifiers and recipient identifiers:

• The did:key method resolves identifiers to a DID document that contains a public key representation without accessing any remote resources by embedding a representation of the key itself in the DID path.
• The did:jwk method is similar to did:key, except the value encoded in the DID path is a base64url-encoded representation of a key in JWK (JSON Web Key) format.
• The did:web method is a quick way to use HTTP URLs with DIDs, because the value in the path of the DID decodes to a URL which is then fetched, resulting in a DID document. It relies on the DNS registration of a domain holder, but many DIDs may be associated with any one domain or subdomain.

Technically, this set of DID methods whose use is commonly observed among early implementers is a narrow range of the DID methods proposed, and each of them lacks some capabilities promoted as possibilities with certain DID methods, such as the ability to rotate keys periodically, recover control after losing relevant keys, or avoidance of the use of DNS. The DID Method Rubric provides a number of relevant comparison factors. Usage of other DID methods may significantly change in the coming years as the consumer technology landscape and open source libraries develop.

The OB 3.0 and CLR 2.0 specifications make no normative requirements strictly limiting which DID methods may be used. Implementers have an incentive to create interoperable experiences with one another through implementing common DID methods and testing interoperability paths for users. In practice, the DID method(s) a credential's Issuer supports being the same as the DID methods Hosts and Displayers (or other wallets and verifiers) support is what governs interoperability.

The Open Badges, CLR and broader Verifiable Credentials ecosystems will take time to converge on reliable interoperability pathways. Specific implementations working together through cooperation and communication will create the opportunities for others to make compatible implementation choices as well as inform future normative specification versions.

The OB and CLR specifications define some requirements around the signing or proving of credentials (see Proofs). Two formats of proof method are introduced, JWTs and Linked Data Proofs. Within each format, there are still a range of options that issuers may select for cryptographically signing the credentials. Notably, signing algorithm selection and its closely related concept of key material expression format must be considered. The best choices within these options sometimes depend on other parts of the issuer's tech stack and which options are supported among wallets and verifiers with whom badge recipients want to share their badges.

The OB specification identifies some specific options, which are used by the conformance test suite to check product implementations. These identified algorithms will likely see the broadest early implementation within Open Badges.

• Linked Data Proofs using the Data Integrity EdDSA Cryptosuites v1.0. Issuers produce an DataIntegrityProof proof referencing a key URL of a public key expressed in eddsa-rdf-2022 format as its verificationMethod.
• JWTs with RSA256 algorithm, with key material published as JSON Web Key (JWK).

A step-by-step guide to signing an OB or CLR is provided in the OB specification section on Proofs. In order to achieve certification, implementers must be able to pass conformance testing with one of the listed methods, but it is expected that the ecosystem will grow as issuers, verifiers, and other services explore new approaches.

It is important to not only prevent unauthorized access to keys and application processes that can trigger signing. At least as important to keeping the signing keys themselves safe is being confident in knowing if keys may have been accessed or compromised with a high degree of confidence. Considerations include:

• Issuers may wish to make use of Hardware Security Modules (HSMs) whenever possible that prevent keys from leaving the device where authorized signing occurs.
• Cloud platform Key Management Services are largely not yet compatible with Ed25519 keys and may not be able to generate the signatures within linked data proofs.
  • HashiCorp Vault (open source or in HashiCorp cloud) offers a Ed25519-compatible sign API via its "Transit" API.
  • Google Cloud Platform supports RSA and ECDSA on the non-NIST secp256k1 curve but not Ed25519.
  • JWT signing with RSA family keys may have broader support in systems like this across all major cloud vendors offering a KMS.

Arguably the most important field for an Achievement is the id, the creator's primary identifier for that achievement. It is expressed as a URI. Two approaches for identifier expression are common, with differing capabilities and slightly different instructions for interpretation:

• Use an HTTPS URL as the identifier: Issuer systems and other achievement publishing systems can publish achievements at the identifier URLs. Clients can use the URL to request the metadata directly from its creator when a client wants an authoritative representation of the issuer's current understanding of the metadata associated with the Achievement. When two OpenBadgeCredentials are issued at different points in time but reference the same Achievement.id, they may contain slightly different representations of the Achievement metadata itself. Relying parties are encouraged to understand the embedded signed data as the representation that the issuer had for the credential at the time it was issued, and they may encounter a different representation embedded in a different credential, which they should understand as a different version of the same achievement. The issuer may use the optional version property to express a label for each of these versions for presentation where relevant. At any point in time, a relying party may request an updated copy of the Achievement from its id URL. If the response returns Achievement data successfully, the client should understand the retrieved metadata to represent the issuer's current understanding of the Achievement. When relying parties encounter the same HTTPS-type achievement ID in AchievmentCredentials across multiple issuers, they can assume that the issuers did intend to recognize the same achievement, as it is defined by its publisher, but they cannot make an assumption that each of the issuers were duly authorized to recognize this achievement by its creator or even that the Achievement honestly represents the identity of its creator, unless the relying party verifies an OpenBadgeCredential referencing this Achievement issued by the creator referenced in the copy of the Achievement retrieved from its ID URL. Future versions of Open Badges may address use cases and normative requirements serving use cases around verifiable authorship of an Achievement or delegation of capabilities related to an Achievement by the Achievement's creator.
• Use a UUID: Issuers sometimes assign an identifier that is assumed to be locally unique to that issuer but cannot be dereferenced. Nevertheless, relying parties may encounter multiple OpenBadgeCredentials that reference an achievement with this ID over time. For OpenBadgeCredentials from the same issuer that reference an Achievement with the same ID, relying parties should interpret these as different versions of the same Achievement. When the same UUID-type Achievement.id is referenced by different issuers across multiple OpenBadgeCredentials, relying parties cannot authoritatively determine that the intent was to recognize the same semantic achievement.

A common use case among Open Badges implementers is for a verifier to expect a particular Achievement claim in an OpenBadgeCredential from a specific issuer. With Open Badges 2.0, it was presumed that verification that an achievement (BadgeClass) was associated with a credential (Assertion) issuer as part of verification, by determining that hosted Achievement IDs were on the same domain as hosted Assertion IDs and/or hosted Issuer IDs. With OB 3.0, some of this capability can no longer be assumed to remain. This is partly because there is no longer a requirement for issuer profiles to use HTTP IDs, but also because integrity verification is assumed to occur at the Verifiable Credentials Data Model level only, because wallets and credentials verifiers will primarily focus on verifying the integrity of the proof on each credential without assumed capacity to verify other relationships represented deeply within these credentials even if OB 3.0 had included such a mechanism in its scope.

The ability to mark a credential as revoked is an important capability for many organizations that make use of Open Badges and CLR. The Verifiable Credentials Data Model v2.0 offers an extensible mechanism by which a credential status resource may be exposed within a credential. Various use cases and solutions have been developed to enable credential status checking with a range of capabilities and implications. OB and CLR reference optional 1EdTech extensions supporting verifiers in obtaining updated representations of credentials and checking for revocation. Issuers and verifiers need to support a common mechanism in order for status checking to work, and yet issuers often need to produce the credential without knowing which other parties might someday rely on it or what methods those verifiers may support. Here are some mechanisms identified by the implementing community for status and revocation management.

• The 1EdTech Revocation List Status Method accompanies the OB and CLR specifications. This enables verifiers to query for status results without revealing to the issuer which specific credential's status is being checked. It does reveal to the requester a list of credential IDs claimed by the issuer to be associated with it, though it is not assumed to be exhaustive or accurate except to indicate the status of the credential known to the requester, because issuers may use multiple lists concurrently, packaged with different sets of credentials and red herrings may appear in some lists. The 1EdTech certification process and validator software will support this status checking method. A reason for revocation may be available for a revoked credential.
• The 1EdTech Credential Refresh Service also accompanies the OB and CLR specifications and enables fetching of an updated version of a credential under inspection by a verifier. The 1EdTech verifier tools will request updated version if such an endpoint is indicated in the badge. There is no approach to authentication or variable authorization defined in this specification, so if an issuer uses it, it is presumed that any client could request the latest version of the credential from this endpoint if they knew the correct URL. Future versions of this specification may serve use cases that require more in-depth protection of refresh endpoints.
• Another option in the space is the Credential Status List 2021 specification, which was adopted as a standards-track specification by the VCWG on December 14th 2022. This protocol enables an issuer to publish a compactly encoded list of status indicator bits covering many credentials at once in an unnamed order. Within each issued credential, the issuer includes a pointer to a specific bit within the bulk status list. This enables verifiers to efficiently query for status results without revealing which specific credential's status is being checked. It does not feature the ability to retrieve a revocation reason for a revoked credential, nor does it provide a refreshed version of the credential consistent with the issuer's latest status data, features that are sometimes bundled with revocation.

IMS Competencies and Academic Standards Exchange (CASE) Service Version 1.0 [CASE-10] specification defines how systems exchange and manage information about learning standards and/or competencies in a consistent and referenceable way.

[CASE-10] defines an information model consisting in, briefly, a container (CFDoc) of a set of academic standard/competency document definitions (CFItem). These CFItem can have associations with others CFItem of another containers, allowing several types of relationships between learning objectives/competences from one institution and another.

In Open Badges and Comprehensive Learner Record, the recording of related skills, competencies, standards, and other associations are enabled by the alignment of an Achievement. This field defines the fields for univocally establish a connection between the Achievement and a node in an educational framework, i.e CFItem.

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "OpenBadgeCredential"],
  "issuer": {
    "id": "https://example.edu/issuers/565049",
    "type": "Profile",
    "name": "Example University"
  },
  "validFrom": "2010-01-01T00:00:00Z",
  "name": "Example University Degree",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": "AchievementSubject",
    "achievement": {
      "id": "https://1edtech.edu/achievements/1",
      "type": "Achievement",
      "criteria": {
        "narrative": "Cite strong and thorough textual evidence to support analysis of what the text says explicitly as well as inferences drawn from the text, including determining where the text leaves matters uncertain"
      },
      "description": "Analyze a sample text",
      "name": "Text analysis",
      "alignment": [{
        "type": "Alignment",
        "targetCode": "74f5bb7d-d7cc-11e8-824f-0242ac160002",
        "targetFramework": "Alabama Course of Study: English Language Arts",
        "targetName": "Cite strong and thorough textual evidence to support analysis of what the text says explicitly as well as inferences drawn from the text, including determining where the text leaves matters uncertain",
        "targetType": "CFItem",
        "targetUrl": "https://caseregistry.imsglobal.org/uri/74f5bb7d-d7cc-11e8-824f-0242ac160002"
      }]
    }
  }
}

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "OpenBadgeCredential"
  ],
  "issuer": {
    "id": "https://example.edu/issuers/565049",
    "type": "Profile",
    "name": "Example University"
  },
  "validFrom": "2010-01-01T00:00:00Z",
  "name": "Example University Degree",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": "AchievementSubject",
    "achievement": {
      "id": "https://1edtech.edu/achievements/1",
      "type": "Achievement",
      "criteria": {
        "narrative": "Cite strong and thorough textual evidence to support analysis of what the text says explicitly as well as inferences drawn from the text, including determining where the text leaves matters uncertain"
      },
      "description": "Analyze a sample text",
      "name": "Text analysis",
      "alignment": [
        {
          "type": "Alignment",
          "targetCode": "74f5bb7d-d7cc-11e8-824f-0242ac160002",
          "targetFramework": "Alabama Course of Study: English Language Arts",
          "targetName": "Cite strong and thorough textual evidence to support analysis of what the text says explicitly as well as inferences drawn from the text, including determining where the text leaves matters uncertain",
          "targetType": "CFItem",
          "targetUrl": "https://caseregistry.imsglobal.org/uri/74f5bb7d-d7cc-11e8-824f-0242ac160002"
        }
      ]
    }
  },
  "proof": [
    {
      "type": "DataIntegrityProof",
      "created": "2024-10-01T07:50:35Z",
      "verificationMethod": "https://example.edu/issuers/565049#z6MkuPF8MKXLqBo7cjx5ve4vjgxBnio3XHY7n3aJMECF3wg3",
      "cryptosuite": "eddsa-rdfc-2022",
      "proofPurpose": "assertionMethod",
      "proofValue": "z3vwGQWeCSTQFPNcXEyySvLzoSazkLYDsk22QHYKVBhhNhbezdV8qGc8S6JFarGGx4LvgX4G9ewKHQ7hh4L2AUhbE"
    }
  ]
}

---------------- JWT header ---------------
{
  "alg": "RS256",
  "typ": "JWT",
  "jwk": {
    "e": "AQAB",
    "kty": "RSA",
    "n": "nzPV7HdRtnmj5xhfPp3fwFb42cezdzig-gNaaWWz162IZizqsiWcY6MAlRFvdF96ABGU1f
ZWjpRj3KzRBD-a9nt5Nf47gxV3s-toofQoZOCgUfruwR3d3Cq-fKU55AKAVkceB7Ll4TEOFhcoh9EMKX
gzbl1mT0OwHD1VXpuIQzLSi-B45GF6YWWf2oxrRX1ajSFGMHJLaC212Y20aafjdvuhnNJxeT0ta6g_b5
i_EYxVPohRtVYh6Cg_liARlEM2GLvUlWININriGGqrx2hm-4Id9ttR5IQF62LH7_MjUJsGS4_KACnD8a
BAcYFpPBOd-Xjb7XMYdaiH53IDMSTAkQ"
  }
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
//       that duplicates the iss, nbf, jti, and sub fields in the
//       Verifiable Credential (vc) field.
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "OpenBadgeCredential"
  ],
  "issuer": {
    "id": "https://example.edu/issuers/565049",
    "type": "Profile",
    "name": "Example University"
  },
  "validFrom": "2010-01-01T00:00:00Z",
  "name": "Example University Degree",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": "AchievementSubject",
    "achievement": {
      "id": "https://1edtech.edu/achievements/1",
      "type": "Achievement",
      "criteria": {
        "narrative": "Cite strong and thorough textual evidence to support analy
sis of what the text says explicitly as well as inferences drawn from the text, 
including determining where the text leaves matters uncertain"
      },
      "description": "Analyze a sample text",
      "name": "Text analysis",
      "alignment": [
        {
          "type": "Alignment",
          "targetCode": "74f5bb7d-d7cc-11e8-824f-0242ac160002",
          "targetFramework": "Alabama Course of Study: English Language Arts",
          "targetName": "Cite strong and thorough textual evidence to support an
alysis of what the text says explicitly as well as inferences drawn from the tex
t, including determining where the text leaves matters uncertain",
          "targetType": "CFItem",
          "targetUrl": "https://caseregistry.imsglobal.org/uri/74f5bb7d-d7cc-11e
8-824f-0242ac160002"
        }
      ]
    }
  },
  "iss": "https://example.edu/issuers/565049",
  "jti": "http://example.edu/credentials/3732",
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6eyJlIjoiQVFBQiIsImt0eSI6IlJTQSIsIm4i
OiJuelBWN0hkUnRubWo1eGhmUHAzZndGYjQyY2V6ZHppZy1nTmFhV1d6MTYySVppenFzaVdjWTZNQWxS
RnZkRjk2QUJHVTFmWldqcFJqM0t6UkJELWE5bnQ1TmY0N2d4VjNzLXRvb2ZRb1pPQ2dVZnJ1d1IzZDND
cS1mS1U1NUFLQVZrY2VCN0xsNFRFT0ZoY29oOUVNS1hnemJsMW1UME93SEQxVlhwdUlRekxTaS1CNDVH
RjZZV1dmMm94clJYMWFqU0ZHTUhKTGFDMjEyWTIwYWFmamR2dWhuTkp4ZVQwdGE2Z19iNWlfRVl4VlBv
aFJ0VlloNkNnX2xpQVJsRU0yR0x2VWxXSU5JTnJpR0dxcngyaG0tNElkOXR0UjVJUUY2MkxIN19NalVK
c0dTNF9LQUNuRDhhQkFjWUZwUEJPZC1YamI3WE1ZZGFpSDUzSURNU1RBa1EifX0.eyJAY29udGV4dCI6
WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3B1cmwuaW1zZ2xv
YmFsLm9yZy9zcGVjL29iL3YzcDAvY29udGV4dC0zLjAuMy5qc29uIl0sImlkIjoiaHR0cDovL2V4YW1w
bGUuZWR1L2NyZWRlbnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiT3Bl
bkJhZGdlQ3JlZGVudGlhbCJdLCJpc3N1ZXIiOnsiaWQiOiJodHRwczovL2V4YW1wbGUuZWR1L2lzc3Vl
cnMvNTY1MDQ5IiwidHlwZSI6IlByb2ZpbGUiLCJuYW1lIjoiRXhhbXBsZSBVbml2ZXJzaXR5In0sInZh
bGlkRnJvbSI6IjIwMTAtMDEtMDFUMDA6MDA6MDBaIiwibmFtZSI6IkV4YW1wbGUgVW5pdmVyc2l0eSBE
ZWdyZWUiLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2
ZjFjMjc2ZTEyZWMyMSIsInR5cGUiOiJBY2hpZXZlbWVudFN1YmplY3QiLCJhY2hpZXZlbWVudCI6eyJp
ZCI6Imh0dHBzOi8vMWVkdGVjaC5lZHUvYWNoaWV2ZW1lbnRzLzEiLCJ0eXBlIjoiQWNoaWV2ZW1lbnQi
LCJjcml0ZXJpYSI6eyJuYXJyYXRpdmUiOiJDaXRlIHN0cm9uZyBhbmQgdGhvcm91Z2ggdGV4dHVhbCBl
dmlkZW5jZSB0byBzdXBwb3J0IGFuYWx5c2lzIG9mIHdoYXQgdGhlIHRleHQgc2F5cyBleHBsaWNpdGx5
IGFzIHdlbGwgYXMgaW5mZXJlbmNlcyBkcmF3biBmcm9tIHRoZSB0ZXh0LCBpbmNsdWRpbmcgZGV0ZXJt
aW5pbmcgd2hlcmUgdGhlIHRleHQgbGVhdmVzIG1hdHRlcnMgdW5jZXJ0YWluIn0sImRlc2NyaXB0aW9u
IjoiQW5hbHl6ZSBhIHNhbXBsZSB0ZXh0IiwibmFtZSI6IlRleHQgYW5hbHlzaXMiLCJhbGlnbm1lbnQi
Olt7InR5cGUiOiJBbGlnbm1lbnQiLCJ0YXJnZXRDb2RlIjoiNzRmNWJiN2QtZDdjYy0xMWU4LTgyNGYt
MDI0MmFjMTYwMDAyIiwidGFyZ2V0RnJhbWV3b3JrIjoiQWxhYmFtYSBDb3Vyc2Ugb2YgU3R1ZHk6IEVu
Z2xpc2ggTGFuZ3VhZ2UgQXJ0cyIsInRhcmdldE5hbWUiOiJDaXRlIHN0cm9uZyBhbmQgdGhvcm91Z2gg
dGV4dHVhbCBldmlkZW5jZSB0byBzdXBwb3J0IGFuYWx5c2lzIG9mIHdoYXQgdGhlIHRleHQgc2F5cyBl
eHBsaWNpdGx5IGFzIHdlbGwgYXMgaW5mZXJlbmNlcyBkcmF3biBmcm9tIHRoZSB0ZXh0LCBpbmNsdWRp
bmcgZGV0ZXJtaW5pbmcgd2hlcmUgdGhlIHRleHQgbGVhdmVzIG1hdHRlcnMgdW5jZXJ0YWluIiwidGFy
Z2V0VHlwZSI6IkNGSXRlbSIsInRhcmdldFVybCI6Imh0dHBzOi8vY2FzZXJlZ2lzdHJ5Lmltc2dsb2Jh
bC5vcmcvdXJpLzc0ZjViYjdkLWQ3Y2MtMTFlOC04MjRmLTAyNDJhYzE2MDAwMiJ9XX19LCJpc3MiOiJo
dHRwczovL2V4YW1wbGUuZWR1L2lzc3VlcnMvNTY1MDQ5IiwianRpIjoiaHR0cDovL2V4YW1wbGUuZWR1
L2NyZWRlbnRpYWxzLzM3MzIiLCJzdWIiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUx
MmVjMjEifQ.LMOEAi84r0v1bU9opVcd75G3LLKBG8nSO7cxD554g5VJA7er5f8wZUKHyFW5IegC-e4Bp
LcYKxLpSxjq8cR8WfVkh0uIn-NkGdRHmHut8tckn0EdBCuL88nP7z0dAaB9fd34eYG7rx6C_Xyba5hFl
4CSKem6bUxasPy619hPGryOZH4QhK2UIRUjSc1u_3_AAFo3qCaBttmbLPjsYJ7MQicFNRQuXt3Ad_Kbx
nT1Dh67lWBs5oGaj054XNtJFtkJWp0C5JXvpqs5vgFBr4XuePa0kqi5i6aBJ25mCxxaChUA5rcpQIKVG
WIjXINEXemtkQ9w4qVQPOGbFI63utquvQ

In Open Badges and Comprehensive Learner Record, it is possible to use alignment to link an achievement to a resource that is described using non-1EdTech vocabularies. Three targetTypes (specifically, ceterms:Credential, ceasn:Competency, and CTDL) have been defined to link to a resource described using the Credential Transparency Description Language (CTDL) family of schema. CTDL defines how credentials, competencies, and many other attributes (such as assessments, courses, programs, transfer value, organizations, and more) can be described in detail and linked to other useful information.

ceterms:Credential is used to establish that a connection is between an achievement and a credential offering described using CTDL. In CTDL, a "credential" can be described using hundreds of defined terms and connections amongst those terms. For example, CTDL can identify a credential as a ‘license’ requiring a particular ‘assessment’ for the demonstration of particular ‘competencies’.

Organizations may publish rich descriptive information about the achievements they offer to the Credential Registry. Credential offering information published to the Registry is available in the Credential Finder application (https://credentialfinder.org/), and issuers of badges for these achievements can link to the page in the Credential Finder using an alignment with targetType of ceterms:Credential using the credential’s CTID.

"achievement": {
  "id": "https://1edtech.edu/achievements/9",
  "type": "Achievement",
  "criteria": {
    "narrative": "Demonstrate a comprehensive understanding of core 3D modeling concepts, successfully create a range of 3D models that meet specified criteria, and pass a practical examination applying foundational techniques in real-time scenarios"
  },
  "description": "Credential for proficiency in the basic techniques and concepts of 3D modeling.",
  "name": "Fundamentals of 3D Modeling Certificate",
  "alignment": [{
    "type": "Alignment",
    "targetCode": "ce-66ae075c-5cc0-4b49-bb15-ea513e1480ac",
    "targetDescription": "Additional information powered by the Credential Registry.",
    "targetName": "Fundamentals of 3D Modeling Certificate",
    "targetFramework": "Credential Transparency Description Language",
    "targetType": "ceterms:Credential",
    "targetUrl": "https://sandbox.credentialengine.org/publisher/credential/ce-66ae075c-5cc0-4b49-bb15-ea513e1480ac"
  }]
}

In Open Badges and Comprehensive Learner Record, it is possible to use alignment to link an achievement to a resource that is described using non-1EdTech vocabularies. Three targetTypes (specifically, ceterms:Credential, ceasn:Competency, and CTDL) have been defined to link to a resource described using the Credential Transparency Description Language (CTDL) family of schema. CTDL defines how credentials, competencies, and many other attributes (such as assessments, courses, programs, transfer value, organizations, and more) can be described in detail and linked to other useful information.

Achievements often align to skills or Competencies, which can be published to the Credential Registry. When aligning to this type of data, use the targetType ceasn:Competency.

"achievement": {
  "id": "https://1edtech.edu/achievements/10",
  "type": "Achievement",
  "criteria": {
    "narrative": "Technical Proficiency: The student's use of 3D modeling tools and techniques should be evident, with smooth surfaces, clean meshes, and appropriate use of textures and materials. The model should be free from technical errors, such as overlapping vertices, and should be optimized for the intended platform or medium."
  },
  "description": "Demonstrated through an academic project requiring an architectural structure, design of a product prototype, simulating a real-world scenario in a virtual environment, and application of 3D modeling principles.",
  "name": "Transform conceptual ideas into tangible 3D representations.",
  "alignment": [{
    "type": "Alignment",
    "targetCode": "ce-e76ee0c4-c455-4cf9-8382-c9d226c69d99",
    "targetDescription": "Additional information powered by the Credential Registry.",
    "targetName": "Transform conceptual ideas into tangible 3D representations.",
    "targetFramework": "Credential Transparency Description Language",
    "targetType": "ceasn:Competency",
    "targetUrl": "https://sandbox.credentialengine.org/finder/competency/ce-e76ee0c4-c455-4cf9-8382-c9d226c69d99"
  }]
}

In Open Badges and Comprehensive Learner Record, it is possible to use alignment to link an achievement to a resource that is described using non-1EdTech vocabularies. Three targetTypes (specifically, ceterms:Credential, ceasn:Competency, and CTDL) have been defined to link to a resource described using the Credential Transparency Description Language (CTDL) family of schema. CTDL defines how credentials, competencies, and many other attributes (such as assessments, courses, programs, transfer value, organizations, and more) can be described in detail and linked to other useful information.

There are many other entity classes that can be described using the CTDL vocabulary. When making an alignment to an Assessment, Learning Opportunity, Job, Occupation, or other entity, use the generic targetType CTDL. This informs consumers to expect CTDL data of one of these other types. Some consumers may simply render a link to the webpage where more information can be retrieved, and others may support fetching the specific data to provide an even richer display. The following example shows how an issuer might express an alignment to a Learning Opportunity Course that has been published to the Credential Registry as CTDL-formatted open data.

"achievement": {
  "id": "https://1edtech.edu/achievements/11",
  "type": "Achievement",
  "criteria": {
    "narrative": "Earns a passing grade."
  },
  "description": "Dive into the world of three-dimensional design with ART 302. This course offers students an immersive experience in transforming abstract concepts into tangible 3D models. Through hands-on projects, expert-led demonstrations, and cutting-edge software tools, learners will master the art of conceptualizing and creating detailed 3D representations. Ideal for aspiring designers, animators, and digital artists, this course emphasizes both technical proficiency and creative expression. Join us and bring your ideas to life in three dimensions!",
  "name": "ART 302: 3D Modeling From Concept to Creation",
  "alignment": [{
    "type": "Alignment",
    "targetCode": "ce-23390b82-eff7-4ff1-894c-9dfe174206be",
    "targetDescription": "Additional information powered by the Credential Registry.",
    "targetName": "ART302: 3D Modeling From Concept to Creation",
    "targetFramework": "Credential Transparency Description Language",
    "targetType": "CTDL",
    "targetUrl": "https://sandbox.credentialengine.org/finder/learningopportunity/ce-23390b82-eff7-4ff1-894c-9dfe174206be"
  }]
}

A Skill Assertion credential is just like a basic OpenBadgeCredential in how an Achievement is included, except that it makes a claim referencing an Achievement that is generic to allow for use by many possible issuers. The Achievement may describe alignment to external competency or skill definitions, such as a CFItem, but the most important aspect of the skill assertion pattern is the shared use of a common achievement that represents a skill or competency across multiple OpenBadgeCredential issuers.

This usage of shared achievements enables consumers to describe specific achievements that they would like learners to hold without being particular about where the learner obtains a credential certifying that achievement. This recognizes the many pathways that lifelong learners find to attain comparable skills.

{
    "@context": [
        "https://www.w3.org/ns/credentials/v2",
        "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
        "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
    ],
    "id": "http://1edtech.edu/credentials/3732",
    "type": ["VerifiableCredential", "OpenBadgeCredential"],
    "name": "Solve and graph linear equations and inequalities",
    "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "type": "AchievementSubject",
        "achievement": {
            "id": "https://example.com/achievements/math/linear-1",
            "type": "Achievement",
            "achievementType": "Competency",
            "creator": {
                "id": "https://example.com/issuers/123767",
                "type": "Profile",
                "name": "Example Industry Group",
                "url": "https://example.com",
                "description": "Example Industry Group is a consortium of luminaries who publish skills data for common usage.",
                "email": "info@exammple.com"
            },
            "criteria": {
                "narrative": "Learners must demonstrate understanding of linear algebra and graphic representation of linear equations."
            },
            "description": "This achievement represents developing capability to solve and graph linear equations and inequalities",
            "image": {
                "id": "https://example.com/achievements/math/linear-1/image",
                "type": "Image",
                "caption": "A line, sloping upward optimistically"
            },
            "name": "Linear equations and inequalities"
        }
    },
    "issuer": {
        "id": "https://1edtech.edu/issuers/565049",
        "type": "Profile",
        "name": "1EdTech University",
        "url": "https://1edtech.edu",
        "phone": "1-222-333-4444",
        "description": "1EdTech University provides online degree programs.",
        "image": {
            "id": "https://1edtech.edu/logo.png",
            "type": "Image",
            "caption": "1EdTech University logo"
        },
        "email": "registrar@1edtech.edu"
    },
    "validFrom": "2022-07-01T00:00:00Z",
    "credentialSchema": [
        {
            "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json",
            "type": "1EdTechJsonSchemaValidator2019"
        }
    ]
}

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
    "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
  ],
  "id": "http://1edtech.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "OpenBadgeCredential"
  ],
  "name": "Solve and graph linear equations and inequalities",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": "AchievementSubject",
    "achievement": {
      "id": "https://example.com/achievements/math/linear-1",
      "type": "Achievement",
      "achievementType": "Competency",
      "creator": {
        "id": "https://example.com/issuers/123767",
        "type": "Profile",
        "name": "Example Industry Group",
        "url": "https://example.com",
        "description": "Example Industry Group is a consortium of luminaries who publish skills data for common usage.",
        "email": "info@exammple.com"
      },
      "criteria": {
        "narrative": "Learners must demonstrate understanding of linear algebra and graphic representation of linear equations."
      },
      "description": "This achievement represents developing capability to solve and graph linear equations and inequalities",
      "image": {
        "id": "https://example.com/achievements/math/linear-1/image",
        "type": "Image",
        "caption": "A line, sloping upward optimistically"
      },
      "name": "Linear equations and inequalities"
    }
  },
  "issuer": {
    "id": "https://1edtech.edu/issuers/565049",
    "type": "Profile",
    "name": "1EdTech University",
    "url": "https://1edtech.edu",
    "phone": "1-222-333-4444",
    "description": "1EdTech University provides online degree programs.",
    "image": {
      "id": "https://1edtech.edu/logo.png",
      "type": "Image",
      "caption": "1EdTech University logo"
    },
    "email": "registrar@1edtech.edu"
  },
  "validFrom": "2022-07-01T00:00:00Z",
  "credentialSchema": [
    {
      "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json",
      "type": "1EdTechJsonSchemaValidator2019"
    }
  ],
  "proof": [
    {
      "type": "DataIntegrityProof",
      "created": "2024-10-01T07:50:36Z",
      "verificationMethod": "https://1edtech.edu/issuers/565049#z6MkqwxmkpyhNNtrEiyYF1kva3jYmx5ge2Vz6qMhsyrScgyq",
      "cryptosuite": "eddsa-rdfc-2022",
      "proofPurpose": "assertionMethod",
      "proofValue": "ztyV4GpZScjh93r3hGX7vtAycMPTXwz114FpSmwH56ga9wGs35hV5D2aFwVYNj9B3z6TTkUdvVqiiimL8yX5yGxy"
    }
  ]
}

---------------- JWT header ---------------
{
  "alg": "RS256",
  "typ": "JWT",
  "jwk": {
    "e": "AQAB",
    "kty": "RSA",
    "n": "6Z5ldT9NJHEapxup_403OC9yjDmkk5_ybvFBopRKO6IJn6GmkQlWD9-G0m49pWLsK6q5rI
4TluxhJa4l3R98Mgkr8m9Ns6Ckg3_eb9qbPjr_MwLWiKImljtZdojm1sfFjTsG9TsHj1q8fjNiw03Pn-
2JR1bCvIoo6RX6gAOOxIM8RTKwOlU76LQrRoVglJsPeebczqm--sDIeCGqaTr6tFOdQkhb-v7L4MUomT
iW997U4QH1ioFN5ScZy4BTN27vC0NPHpTzU2dePwG6mZmy20Luj4nzrS9XUaloktBgO7FsSW5avWgI1-
guSEmgNlPUZ_kXLRLxcKzUzmoza5cemw"
  }
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
//       that duplicates the iss, nbf, jti, and sub fields in the
//       Verifiable Credential (vc) field.
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
    "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
  ],
  "id": "http://1edtech.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "OpenBadgeCredential"
  ],
  "name": "Solve and graph linear equations and inequalities",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": "AchievementSubject",
    "achievement": {
      "id": "https://example.com/achievements/math/linear-1",
      "type": "Achievement",
      "achievementType": "Competency",
      "creator": {
        "id": "https://example.com/issuers/123767",
        "type": "Profile",
        "name": "Example Industry Group",
        "url": "https://example.com",
        "description": "Example Industry Group is a consortium of luminaries who
 publish skills data for common usage.",
        "email": "info@exammple.com"
      },
      "criteria": {
        "narrative": "Learners must demonstrate understanding of linear algebra 
and graphic representation of linear equations."
      },
      "description": "This achievement represents developing capability to solve
 and graph linear equations and inequalities",
      "image": {
        "id": "https://example.com/achievements/math/linear-1/image",
        "type": "Image",
        "caption": "A line, sloping upward optimistically"
      },
      "name": "Linear equations and inequalities"
    }
  },
  "issuer": {
    "id": "https://1edtech.edu/issuers/565049",
    "type": "Profile",
    "name": "1EdTech University",
    "url": "https://1edtech.edu",
    "phone": "1-222-333-4444",
    "description": "1EdTech University provides online degree programs.",
    "image": {
      "id": "https://1edtech.edu/logo.png",
      "type": "Image",
      "caption": "1EdTech University logo"
    },
    "email": "registrar@1edtech.edu"
  },
  "validFrom": "2022-07-01T00:00:00Z",
  "credentialSchema": [
    {
      "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achieve
mentcredential_schema.json",
      "type": "1EdTechJsonSchemaValidator2019"
    }
  ],
  "iss": "https://1edtech.edu/issuers/565049",
  "jti": "http://1edtech.edu/credentials/3732",
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6eyJlIjoiQVFBQiIsImt0eSI6IlJTQSIsIm4i
OiI2WjVsZFQ5TkpIRWFweHVwXzQwM09DOXlqRG1razVfeWJ2RkJvcFJLTzZJSm42R21rUWxXRDktRzBt
NDlwV0xzSzZxNXJJNFRsdXhoSmE0bDNSOThNZ2tyOG05TnM2Q2tnM19lYjlxYlBqcl9Nd0xXaUtJbWxq
dFpkb2ptMXNmRmpUc0c5VHNIajFxOGZqTml3MDNQbi0ySlIxYkN2SW9vNlJYNmdBT094SU04UlRLd09s
VTc2TFFyUm9WZ2xKc1BlZWJjenFtLS1zREllQ0dxYVRyNnRGT2RRa2hiLXY3TDRNVW9tVGlXOTk3VTRR
SDFpb0ZONVNjWnk0QlROMjd2QzBOUEhwVHpVMmRlUHdHNm1abXkyMEx1ajRuenJTOVhVYWxva3RCZ083
RnNTVzVhdldnSTEtZ3VTRW1nTmxQVVpfa1hMUkx4Y0t6VXptb3phNWNlbXcifX0.eyJAY29udGV4dCI6
WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3B1cmwuaW1zZ2xv
YmFsLm9yZy9zcGVjL29iL3YzcDAvY29udGV4dC0zLjAuMy5qc29uIiwiaHR0cHM6Ly9wdXJsLmltc2ds
b2JhbC5vcmcvc3BlYy9vYi92M3AwL2V4dGVuc2lvbnMuanNvbiJdLCJpZCI6Imh0dHA6Ly8xZWR0ZWNo
LmVkdS9jcmVkZW50aWFscy8zNzMyIiwidHlwZSI6WyJWZXJpZmlhYmxlQ3JlZGVudGlhbCIsIk9wZW5C
YWRnZUNyZWRlbnRpYWwiXSwibmFtZSI6IlNvbHZlIGFuZCBncmFwaCBsaW5lYXIgZXF1YXRpb25zIGFu
ZCBpbmVxdWFsaXRpZXMiLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6ImRpZDpleGFtcGxlOmViZmVi
MWY3MTJlYmM2ZjFjMjc2ZTEyZWMyMSIsInR5cGUiOiJBY2hpZXZlbWVudFN1YmplY3QiLCJhY2hpZXZl
bWVudCI6eyJpZCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWNoaWV2ZW1lbnRzL21hdGgvbGluZWFyLTEi
LCJ0eXBlIjoiQWNoaWV2ZW1lbnQiLCJhY2hpZXZlbWVudFR5cGUiOiJDb21wZXRlbmN5IiwiY3JlYXRv
ciI6eyJpZCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vaXNzdWVycy8xMjM3NjciLCJ0eXBlIjoiUHJvZmls
ZSIsIm5hbWUiOiJFeGFtcGxlIEluZHVzdHJ5IEdyb3VwIiwidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNv
bSIsImRlc2NyaXB0aW9uIjoiRXhhbXBsZSBJbmR1c3RyeSBHcm91cCBpcyBhIGNvbnNvcnRpdW0gb2Yg
bHVtaW5hcmllcyB3aG8gcHVibGlzaCBza2lsbHMgZGF0YSBmb3IgY29tbW9uIHVzYWdlLiIsImVtYWls
IjoiaW5mb0BleGFtbXBsZS5jb20ifSwiY3JpdGVyaWEiOnsibmFycmF0aXZlIjoiTGVhcm5lcnMgbXVz
dCBkZW1vbnN0cmF0ZSB1bmRlcnN0YW5kaW5nIG9mIGxpbmVhciBhbGdlYnJhIGFuZCBncmFwaGljIHJl
cHJlc2VudGF0aW9uIG9mIGxpbmVhciBlcXVhdGlvbnMuIn0sImRlc2NyaXB0aW9uIjoiVGhpcyBhY2hp
ZXZlbWVudCByZXByZXNlbnRzIGRldmVsb3BpbmcgY2FwYWJpbGl0eSB0byBzb2x2ZSBhbmQgZ3JhcGgg
bGluZWFyIGVxdWF0aW9ucyBhbmQgaW5lcXVhbGl0aWVzIiwiaW1hZ2UiOnsiaWQiOiJodHRwczovL2V4
YW1wbGUuY29tL2FjaGlldmVtZW50cy9tYXRoL2xpbmVhci0xL2ltYWdlIiwidHlwZSI6IkltYWdlIiwi
Y2FwdGlvbiI6IkEgbGluZSwgc2xvcGluZyB1cHdhcmQgb3B0aW1pc3RpY2FsbHkifSwibmFtZSI6Ikxp
bmVhciBlcXVhdGlvbnMgYW5kIGluZXF1YWxpdGllcyJ9fSwiaXNzdWVyIjp7ImlkIjoiaHR0cHM6Ly8x
ZWR0ZWNoLmVkdS9pc3N1ZXJzLzU2NTA0OSIsInR5cGUiOiJQcm9maWxlIiwibmFtZSI6IjFFZFRlY2gg
VW5pdmVyc2l0eSIsInVybCI6Imh0dHBzOi8vMWVkdGVjaC5lZHUiLCJwaG9uZSI6IjEtMjIyLTMzMy00
NDQ0IiwiZGVzY3JpcHRpb24iOiIxRWRUZWNoIFVuaXZlcnNpdHkgcHJvdmlkZXMgb25saW5lIGRlZ3Jl
ZSBwcm9ncmFtcy4iLCJpbWFnZSI6eyJpZCI6Imh0dHBzOi8vMWVkdGVjaC5lZHUvbG9nby5wbmciLCJ0
eXBlIjoiSW1hZ2UiLCJjYXB0aW9uIjoiMUVkVGVjaCBVbml2ZXJzaXR5IGxvZ28ifSwiZW1haWwiOiJy
ZWdpc3RyYXJAMWVkdGVjaC5lZHUifSwidmFsaWRGcm9tIjoiMjAyMi0wNy0wMVQwMDowMDowMFoiLCJj
cmVkZW50aWFsU2NoZW1hIjpbeyJpZCI6Imh0dHBzOi8vcHVybC5pbXNnbG9iYWwub3JnL3NwZWMvb2Iv
djNwMC9zY2hlbWEvanNvbi9vYl92M3AwX2FjaGlldmVtZW50Y3JlZGVudGlhbF9zY2hlbWEuanNvbiIs
InR5cGUiOiIxRWRUZWNoSnNvblNjaGVtYVZhbGlkYXRvcjIwMTkifV0sImlzcyI6Imh0dHBzOi8vMWVk
dGVjaC5lZHUvaXNzdWVycy81NjUwNDkiLCJqdGkiOiJodHRwOi8vMWVkdGVjaC5lZHUvY3JlZGVudGlh
bHMvMzczMiIsInN1YiI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMyMSJ9.nXQ
5IqeBgiR3lc9Q9Lq7ivSCLxOC8gMWXmb8M4g6Fqb2CZ50K65mbNyyMdXutq4oH2rrGdLWLGQyVKCditQ
_SR4KE1ch4YICcE0a2Z42JYNB6z-OIX2Oy2bTt3ptbVwFL-3VifaIPHFxdRpz2k4qP2nmMRgKn_OfEsa
J46UcgjI-lRH25nzy0oV_T4J2wi4qbBvkuowzE2zntfMGiq5RWChaIu4TeGjHwgbFPcb_TItbbYDDlRa
CzAAuQB6DTil66pnqgoJadpdJK7dZyuUhOja2Czfz1vFg0uxDNFs50Z4e-I9OMvv8JSlkRPtcGbPqqsb
BMFPWqPoi6zmWWeBf6g

Sometimes issuers want credentials to be shareable to audiences who are not capable of authenticating subjects via an identifier such as a DID. Many of these use cases may be served by including one or more email identifiers. (Only partial data is shown for clarity, for example omitting the achievement claim within credentialSubject.)

{
    "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "type": "AchievementSubject",
        "identifier": [
            {
                "type": "IdentityObject",
                "hashed": false,
                "identityHash": "a.exampleton@example.edu",
                "identityType": "emailAddress"
            }
        ]
    }
}

If the known email address for the user is expected to no longer be a useful source of authentication, such as if the user loses access to a work or university email after leaving that organization (perhaps 6 months after graduation), an issuer may wish to provide additional identifying information, such as a name.

{
    "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "type": "AchievementSubject",
        "identifier": [
            {
                "type": "IdentityObject",
                "hashed": false,
                "identityHash": "Albert Exampleton",
                "identityType": "ext:name"
            }
        ]
    }
}

Inclusion of additional personally identifiable information about the subject, especially with "hashed": false, reduces the potential anonymity of the subject. Those with whom the credential is shared may share it to others, who would be able to view this identifying information. While sharing typically passes through control of the subject/holder, different issuers may weigh the potential benefits of including this information against the risks of unauthorized disclosure.

If issuers desire to include much more information about the subject in the credential, they may add the Profile type and include additional properties from Profile. The above approach using IdentityObject is expected to be more broadly usable, because displayers of OpenBadgeCredentials will expect this type of data. Additional data from Profile is not expected directly within credentialSubject, so it is less likely that displayers would build custom handling for these unexpected properties. An "advanced" view where users may review the JSON data directly may be included in some displayer products, in which case viewers would be able to review this information more directly.

{
    "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "type": ["AchievementSubject", "Profile"],
        "givenName": "Albert",
        "familyName": "Exampleton"
    }
}

Issuers can add a description of the work that the recipient did to earn the achievement via the evidence attribute of AchievementCredential. This description can be a page that links out to other pages if linking directly to the work is infeasible.

The id property also can be the evidence encoded as a Data URI. However, embedding the evidence as Data URI as the id of the evidence has some caveats:

• Due to the JSON-LD canonicalization process for signing, there's a row for each field of the evidence with the id inside. If the id is the evidence itself as Data URI, the size of the payload to process grows significantly, moreover when evidence has 5 fields and is extensible.
• Some libraries fails when processing this.

Also attempting to embed large data in a credential JSON is not recommended. You should expect uneven interop performance if you do that.

Instead, the recommendation for embedding the evidence is:

1. use a urn: URI for the id.
2. have a separate property (data or whatever works) that contains the text-encoded data.

Keys used in proof generation must belong to the issuer. However, there isn't a existing way in current standards to completely assure this provenance.

The following best practices establish a verification mechanism to assure that the issuer is the owner of the key used in a credential.

Results or evidence fields may contain data that should be kept confidential or require learner’s consent to disclose. These includes items such as grade data or evidence documents that may have personally identifiable information (PII). Unless it is protected, this data will be transmitted in a “SHARE” transmission of the full payload (i.e.: Baked image, API request, or Web link to an HTML version of a credential) or in a verified presentation request from a verifier application.

The verified credentials data model 2.0 outlines ways that verified credentials (VCs) can manage data privacy by either an enveloping proof or an embedded proof. The BBS or SD-JWT signing methods can support selective disclosure or encryption of the data (such as with TLS), while a Linked Data Proof does not. CBOR encoding can also be used within the JSON of a credential for selective disclosure so only parts of the specific badge data are shared and can handle the inclusion of zero-knowledge proofs. CBOR can be used with the SD-JWT or LinkedData Proof methods but only manages the selective disclosure and encryption of the protected data at the time of the verified presentation request.

It is recommended that the issuer provide information on which fields may be governed by selective disclosure and the method used in the beginning of the credential payload.

In the case where an issuer is intending to implement credentials for the purpose of documenting all academic activity, grade data might include such use cases as work that is in progress, on hold, provisional, withdrawn, or failed. In this case, it should be required for the issuer to include the ResultStatus. Learners should not be able to disassociate the context of this status from their results if a Holder application implements selective disclosure.

In the case that a link is included as evidence, it should be immutable. Links that a learner or another party has access to edit (i.e.: YouTube, photo sharing site, document sharing site, etc.) should not be used in a verified credential so that the file is always in the same state as when the credential was issued. The issuer may wish to implement some form of password access control to links and a mechanism for the learner to approve access. It is advisable for Holder applications to implement a process for a verifying application to disclose their identity or reason for a verified presentation request (e.g.: “I need to verify that the course was completed with a passing grade”).

Linked data proofs imply the use of a cryptosuite for its generation and further verification. The Open Badges 3.0 and Comprehensive Learner Record 2.0 specifications define the cryptosuite to use.

The change of the cryptosuite has impact in newly issued credentials. But there are already issued credentials with a proof generated using a now old cryptosuite. Verifiers should support prior cryptosuites, specially when the credential doesn't define the refresh service. In that case, is argually that the issuer will provide a refreshed version of the credential with a proof computed with the current designed cryptosuite.

Prior designed cryptosuites in both OB 3.0 and CLR 2.0 were:

• eddsa-2022
• Ed25519Signature2020

Keys used in proof generation must belong to the issuer. However, there isn't a existing way in current standards to completely assure this provenance.

The following best practices establish a verification mechanism to assure that the issuer is the owner of the key used in a credential.

Consider the following example two products using the OB 3.0 API to interact:

Example: Sending an Open Badge to a credential backpack via API

Luis is in college pursuing a technical degree. He completes an assessment in class and receives a grade. He is notified by email that he has earned a badge and clicks through, where he is authenticated to the college's student Open Badges portal using his college single sign on. He sees that he has actually earned two badges, each representing competencies, that were assessed by his instructor. The website says the CLR is ready to save, so Luis selects that option. The application shows him a list of two credential backpack providers he can use to save. There is an advanced toggle that reveals an additional option to enter a service provider URL, but Luis closes that and picks one of the known options that looks good and has a good privacy policy. He selects that option and is directed to the backpack site where he signs up for an account. After he completes registration, he is prompted that he may return to the Open Badges portal to complete receiving his credential. He confirms and appears back in the Open Badges portal, where a confirmation message greets him saying all credentials were successfully transferred. He then confirms to return once more to the backpack site, where sees the two Open Badges representing his competencies.

Luis looks at a page detailing the metadata of the first achievement, including the achievement type of Competency and a description of what he had been working to learn. He thinks that being able to look back at these and see the description will help him prepare for job interviews in the future.

Luis sees an option to share his competency badge to a social media site. He proceeds and is prompted to customize sharing settings, including whether anyone with the link is able to view full verifiable details or if viewers need to request access. He selects full details and shares the generated URL to a professional social network site, where a preview card appears including relevant keywords for the competency. His post receives a like from one of Luis's friends immediately.

This is a long user workflow. What makes this interaction successful?

• These products each have a clear sense of their scope of responsibility. One is the "Issuer" of the Open Badges, the other is the "Backpack". They can each implement the necessary parts of the experience that fits their role and not invest deeply in other parts. For example, the issuer platform doesn't need to offer a system of sharing URLs and online access control management, all it does is sign the credential and implement the Client side of the Open Badges API. The Backpack handles the sharing, including giving Luis significant control over URL-based access. This takes product focus.
• Known-successful integrations are highlighted in the experience. This takes cooperation between implementation partners, but the benefit is clear: Luis doesn't need to know what an Open Badge is or how to find a compatible backpack on the TrustEd Apps Directory in order to take advantage of his credential. Tested compatibility paths and instructions on how to take the next step are provided as the primary choice for non-advanced users.
• The backpack platform implemented the Open Graph Protocol for the sharing URL, better supporting the social network site's generation of a preview card that included the badge image and a relevant title and content snippet.

Other recommendations related to implementing the API include:

• Service provider (host) platforms represent the learner (resource owner) in interactions that allow that learner to share their credentials with relying parties. In order to give the learner adequate control over sharing, hosts should recognize that learners may want to use their system for multiple different partially overlapping uses. For example, a learner might hold formal professional credentials and informal social badges in the same account. Hosts should give the learner the ability to attenuate access grants to read their badges so that certain service consumers (read) can only access badges that the user has designated for that purpose. The mechanism to do this may vary across different systems. For example, a host might enable a learner to gather badges into collections and may make it possible to select one or more collections when making an access grant. The consumer application they grant access to will be able to read any badges added to the collection at the time of the request, even if the badge is added to the collection after the original access grant was approved.
• Products should take into account many factors and opportunities for user failure including high conceptual complexity or use of jargon, forgotten passwords or no-longer working email addresses, and potential incompatibilities due to differing choices of DID methods, key formats/signature suites, or credential exchange protocol choices across different certifiable products.

The OB API enables key use cases for interoperability between web services that manage Open Badges on holders' behalf. This is centered on an ecosystem of backpacks and clients. "Backpack" and "web wallet" are commonly used terms to refer to a web service that holds Open Badges and/or CLR credentials for learners, enabling them to manage and share them. Clients each often primarily act to issue credentials or to verify credentials to display or convert into local understanding of someone's capabilities and accomplishments. Typically learners authorize issuers to send their credentials to backpacks and then from those backpacks, authorize verifier clients to access them.

This is an ambitious ecosystem to propose, even though users are familiar with the underlying OAuth and OpenID Connect experiences that tie together dozens of their online accounts. There is the addition of dynamic client registration and the wide variety of optional components these specifications feature. Implementers should prioritize high success-rate user experiences in credential acceptance.

Products that best aim to teach users a controlled number of concepts and provide interfaces offering easy successful options for the most common actions have a better chance of ensuring learners can take advantage of their digital credentials. No learner should be disadvantaged by poor interoperability experiences and dead ends.

As ClrCredentials bundle a number of individual OpenBadgeCredentials together, they sometimes offer additional information about the relationships between elements. Implementations of the CLR API should be done for use cases where the signed bundles (signed by the original issuers) or the inclusion of associations provides benefit to users.

Example: Sending a CLR to a credential backpack (host) via API

Luis achieved his Associate Degree and is looking for jobs. He is notified by email that his CLR is ready and clicks through, where he is authenticated to the college's student CLR portal using his college single sign on. He sees the CLRCredential. This is his first CLR, and he wants to see how to use it to help his job search.

The website says the CLR is ready to save, so Luis selects that option. The application shows him a list of two credential backpack providers he can use to save. There is an advanced toggle that reveals an additional option to enter a service provider URL, but Luis closes that and picks one of the known options that looks good and has a good privacy policy. He selects that option and is directed to the backpack site where he signs up for an account. After he completes registration, he is prompted that he may return to the CLR portal to complete receiving his credential. He confirms and appears back in the CLR portal, where a confirmation message greets him saying all credentials were successfully transferred. He then confirms to return once more to the backpack site, where sees the CLR Credential and all the individual Achievement Credentials within it representing the degree, the courses he took, and the competencies he mastered.

While the OB 3.0 and CLR 2.0 APIs serve use cases for web services to verifiably exchange credentials on behalf of holders, the Verifiable Credentials community is exploring how more portable wallets, often operating on mobile devices which cannot serve HTTP requests can serve additional use cases. All Verifiable Credentials, including Open Badges and CLRs can and will be communicated over a range of protocols. This is a space that is seeing significant experimentation pre-standardization.

Implementers are encouraged to cooperate through communities like 1EdTech to ensure high-quality user experience in the exchange of credentials between their products, both via OB and CLR APIs and emerging protocols to carry these credentials into next-generation use cases. When new user experience patterns are presented that aim to become universal, take care to help the user through the workflow, and give them fallback solutions whenever possible.

Protocols under development to transport Verifiable Credentials including Open Badges and CLR include Credential Handler API (CHAPI), DIDComm, and OID4VC.

Example: The experience of a learner who receives their CLR

Luis now is viewing his CLR in his backpack, a web service that holds Open Badges & CLR Verifiable Credentials on his behalf:

Luis is looking at his college's CLR portal. He sees these credentials are set to be issued to his college email address, but he just graduated and will lose access to that email address in 6 months. There is an option to prove control of a personal address and have the credentials issued to that address, but Luis also sees another option to connect a wallet on his mobile device, where he can use a securely generated passkey to create a cryptographically verifiable Decentralized Identifier (DID) to use. Links appear to mobile app stores for several mobile wallet options.

Luis puts it off until Saturday but then reads a little about Verifiable Credentials and is interested to try out replacing his soon-to-expire email address with a DID. He chooses one of the wallet options that works on his device and sets it up. Back at the CLR portal on his desktop computer, he selects to proceed to connect to a mobile wallet. He chooses the CLR Credential and several of the competency achievements to send to the wallet initially. He is directed to an experience where through scanning a QR code displayed on screen and confirming some details on his phone, he is shown that there is a successful connection, and that credentials have been downloaded to the wallet. He sees them on his phone, which says he'll be able to use them in the future on websites that use Verifiable Credentials.

Here, Luis walks through the experience of downloading a mobile app to use as a wallet for credentials including his CLRCredential and several OpenBadgeCredentials. This issuer app seems to be compatible with a wide variety of web wallets, perhaps even through implementing multiple protocols used by these wallets with a variety of options. Some issuer services may be operating with connections to fewer or different wallet applications.

Some recommendations for pre-standardization implementation of service connection protocols include:

• Test integrations and communicate with your implementation partners for the benefit of users' experience.
• Share pain points (without exposing personal information) and learn about possible solutions from others.
• Accurately inform users of the experimental status of features and integrations as necessary. Giving users an accurate sense of whether they are traveling a smooth and well-trodden path or a new route that may have pitfalls or dead ends goes a long way to gaining user trust.
• Prioritize tested high-success pathways to product integration.
• Provide some opportunities for users who desire it to learn about the work your product is doing under the hood to take care of their important data and empower them as participants in non-monopolistic ecosystems using open standards.
• Give users fallback options that are likely to succeed if the first path they try fails. For example, offer the chance to choose any wallet that uses a certain supported protocol, but suggest one particular integration as an easy choice, so users don't get stuck if the wallet they previously used for a different issuer doesn't work with the protocol used on your site. If all else fails, maybe a signed credential in a JSON download is an adequate compromise.
• Present benefits and risks to user to help them understand their choices. This example emphasized the user-owned nature of DIDs enabled by wallet connection in the face of the potential loss of control of an institutional or organizational email identifier. Products should make users aware of risks, such as any loss of data or verifiability that might be caused by losing a physical device.

The first step is to define a custom JSON-LD context with the added attributes. Following our example extension, it would be as follows:

{
  "@context": {
    "@protected": true,
    "id": "@id",
    "type": "@type",
    "MyCustomAchievement": {
      "@id" : "http://your_url/vocabulary#MyCustomAchievement",
      "@context": {
        "@protected": true,
        "id": "@id",
        "type": "@type",
        "myField": {
          "@id": "https://schema.org/description"
        },
        "anotherField": {
          "@id": "https://your_url/vocabulary#anotherField",
          "@type": "xsd:dateTime"
        }
      }
    }
  }
}

Your credentials MUST include this context in their @context. ie:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
    "https://your_url/your_context"
  ]
  ...
}

In this example, “https://your_url/your_context” resolves to the above JSON-LD context. Also, the Achievement in your credentials MUST also be of your newly created type. i.e.:

{
  ...
  "credentialSubject": {
    ...
    "achievement": {
      "type": ["Achievement", "MyCustomAchievement"]
      ...
    }
  }
  ...
}

The next step is to define a custom Define a JSON schema for your new type. Following our example extension, it would be as follows:

{
  "$schema": "https://json-schema.org/draft/2019-09/schema#",
  "$id": "https://your_url/your_schema.json",
  "type": "object",
  "properties": {
    "credentialSubject": {
      "type": "object",
      "properties": {
        "achievement": {
          "type": "object",
          "properties": {
            "myField": {
              "type": "string"
            },
            "anotherField": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": ["myField"],
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Your credentials MUST include this schema in the credentialSchemaProperty so verifiers can check them against your schema. I.e:

{
  ...
  "credentialSchema": [{
    "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json",
    "type": "1EdTechJsonSchemaValidator2019"
  }, {
    "id": "https://your_url/your_schema.json",
    "type": "1EdTechJsonSchemaValidator2019"
  }]
  ...
}