Concepts

Concepts#

This section explains the key concepts behind the learning-credentials service.

Credential Lifecycle#

A credential goes through the following statuses during its lifecycle:

  1. GENERATING — The credential generation task has started (e.g., the PDF is being created and uploaded).

  2. AVAILABLE — The credential has been successfully generated and is available for download.

  3. ERROR — The generation process failed. The credential can be regenerated by running the generation task again.

  4. INVALIDATED — The credential has been invalidated (e.g., due to a name change or reissue). The PDF is archived and made inaccessible.

digraph lifecycle { rankdir=LR node [shape=box, style=filled, fillcolor=gray95] GENERATING -> AVAILABLE [label="success"] GENERATING -> ERROR [label="failure"] ERROR -> GENERATING [label="retry"] AVAILABLE -> INVALIDATED [label="invalidate\nor reissue"] }

Credential Types and Configurations#

The system separates what a credential is from where it applies:

  • CredentialType: A reusable definition specifying the retrieval function (who is eligible), the generation function (how to create the credential), and default custom options. For example, “Certificate of Completion” or “Certificate of Achievement”.

  • CredentialConfiguration: Links a credential type to a specific learning context (course or Learning Path). It can override the default custom options from the type and define a schedule for automatic generation.

This separation allows a single credential type to be reused across many courses while allowing per-course customization.

Retrieval and Generation Functions#

Credential processing is split into two pluggable steps:

  • Retrieval functions (prefixed with retrieve_) determine which users are eligible for a credential. They check criteria such as grades, completion percentages, or a combination of both.

  • Generation functions (prefixed with generate_) create the actual credential artifact (e.g., a PDF). They receive eligible user data and produce a downloadable credential.

Both function types are auto-discovered via reflection and can be extended by adding new functions to the respective modules.

Verification#

Each credential has two UUIDs:

  • uuid (primary key): Used internally to identify the credential. Not exposed publicly.

  • verify_uuid: A separate UUID used for third-party verification. This UUID can be embedded on the PDF (via the {verify_uuid} placeholder) and used with the public metadata API to verify a credential’s authenticity and status.

The public verification API endpoint (/api/learning_credentials/v1/metadata/<verify_uuid>/) returns the credential’s metadata including the holder’s name, issue date, learning context, status, and any invalidation reason. This allows employers or other third parties to verify credentials without authentication.