CLR - Timeback Docs (Beta)

@timeback/clr and timeback-clr wrap the authenticated CLR v2.0 API. The client exposes credentials.upsert() and discovery.get().

Install

npm install @timeback/clr

pip install timeback-clr

Credential contract

credentials.upsert() sends POST /ims/clr/v2p0/credentials/. The receiver creates or updates a record identified by credential id and issuer id, returning the stored credential with HTTP 201 or 200. This path does not add a signature, verify a supplied proof, or aggregate a student’s records automatically. The receiver requires:

Three ordered contexts: W3C credentials v2, CLR v2, then Open Badges v3.
type containing both VerifiableCredential and ClrCredential.
An issuer profile, credential name, URI identifier and ISO date in validFrom.
A ClrSubject with at least one nested verifiableCredential.
At least one top-level credentialSubject.achievement. This is an additional receiver requirement: an achievement nested only inside a child credential is insufficient. Each achievement needs an ID, type, name, description and criteria.

Optional email identity entries are resolved to a Timeback student; an unknown email fails the request. Existing proofs are data in this upsert path, not evidence that this endpoint verified or issued the credential.

Example

This example illustrates the accepted structure. Replace the sample issuer, learner, achievement and credential records with your own authorized records before submitting.

credential.json

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/clr/v2p0/context-2.0.1",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3"
  ],
  "id": "https://example.edu/credentials/transcript-001",
  "type": [
    "VerifiableCredential",
    "ClrCredential"
  ],
  "issuer": {
    "id": "https://example.edu",
    "type": [
      "Profile"
    ],
    "name": "Example University"
  },
  "name": "Example achievement record",
  "validFrom": "2026-01-01T00:00:00Z",
  "credentialSubject": {
    "id": "https://example.edu/learners/example",
    "type": [
      "ClrSubject"
    ],
    "achievement": [
      {
        "id": "https://example.edu/achievements/algebra-1",
        "type": [
          "Achievement"
        ],
        "name": "Algebra I",
        "description": "Example achievement supplied by the issuer.",
        "criteria": {
          "narrative": "Meets the issuing organization's documented requirements."
        },
        "achievementType": "Course"
      }
    ],
    "verifiableCredential": [
      {
        "@context": [
          "https://www.w3.org/ns/credentials/v2"
        ],
        "id": "https://example.edu/credentials/algebra-001",
        "type": [
          "VerifiableCredential",
          "AchievementCredential"
        ],
        "issuer": {
          "id": "https://example.edu",
          "type": [
            "Profile"
          ],
          "name": "Example University"
        },
        "validFrom": "2026-01-01T00:00:00Z",
        "credentialSubject": {
          "id": "https://example.edu/learners/example"
        }
      }
    ]
  }
}

import { readFile } from 'node:fs/promises'
import { ClrClient } from '@timeback/clr'

const client = new ClrClient({
  env: 'staging',
  auth: {
    clientId: process.env.CLR_CLIENT_ID!,
    clientSecret: process.env.CLR_CLIENT_SECRET!,
  },
})
const credential = JSON.parse(await readFile('credential.json', 'utf8'))
const stored = await client.credentials.upsert(credential)
const discovery = await client.discovery.get()

import json
import os
from pathlib import Path
from timeback_clr import ClrClient

client = ClrClient(
    env="staging",
    client_id=os.environ["CLR_CLIENT_ID"],
    client_secret=os.environ["CLR_CLIENT_SECRET"],
)
credential = json.loads(Path("credential.json").read_text())
stored = await client.credentials.upsert(credential)
discovery = await client.discovery.get()

TypeScript validates the input with Zod; Python validates and serializes its input model. The receiver validates again. Successful client validation alone does not satisfy the receiver’s achievement requirement.

Discovery and composition

discovery.get() calls the authenticated discovery endpoint and returns its OpenAPI document. Route descriptions may describe intended capabilities; credential signing is not implemented by the reviewed upsert handler. The same resources are available through timeback.clr on the Core client. Standalone configuration supports environment mode, explicit base/auth URLs, or a shared TimebackProvider; the optional request timeout is milliseconds in TypeScript and seconds in Python.

Errors

import { ClrError } from '@timeback/clr/errors'

try {
  await client.credentials.upsert(credential)
} catch (error) {
  if (error instanceof ClrError) {
    console.error(error.statusCode, error.message)
  } else {
    throw error
  }
}

from timeback_clr import ClrError

try:
    await client.credentials.upsert(credential)
except ClrError as error:
    print(error)

Input validation errors can occur before a request; HTTP error handling is separate. Check the response and your stored record rather than assuming an upsert produced a signed credential.

​Install

​Credential contract

​Example

​Discovery and composition

​Errors

Install

Credential contract

Example

Discovery and composition

Errors