Skip to content

credly-setup-guide.md

Latest commit

 

History

History
87 lines (57 loc) · 6.51 KB

credly-setup-guide.md

File metadata and controls

87 lines (57 loc) · 6.51 KB

Credly Setup Guide

This guide walks the DRI through Credly configuration before the first delivery of the workshop. Once the badge template is created and the API key is provisioned, no per-event Credly work is needed; the same configuration serves all subsequent events.

You need an organization administrator account on Credly for the MongoDB issuing organization. If you do not have admin rights, contact the team that manages MongoDB's Credly organization (typically MongoDB University or the MongoDB Education team) before going further.

Prerequisites

You need:

  • Admin access to the MongoDB Credly organization on credly.com.
  • The organization id (a UUID). You can find it under Organization Management in the Credly admin UI, or extract it from any existing badge template URL on Credly: https://www.credly.com/org/<vanity>/badge/<template> is the public URL, and the API URL surfaces the UUID.
  • Final badge artwork (PNG, ideally 600x600, transparent background). MongoDB Education has a standard template for workshop badges; use that.
  • The badge name, description, criteria URL, and skill tags, agreed with whoever owns MongoDB's badge taxonomy.

Step 1: Create the badge template

In the Credly admin UI:

  1. Navigate to Manage → Badge Templates → Create Badge Template.
  2. Set the template type to Badge (not Certification).
  3. Enter:
    • Name: AI Coding with MongoDB Workshop
    • Description: A short paragraph naming what the earner demonstrated. Suggested: "Earned for completing the AI Coding with MongoDB Workshop workshop, including designing a MongoDB schema for application access patterns, scaffolding a working API with MongoDB Agent Skills, using the MongoDB MCP Server to refine the schema against live data, and producing a schema summary that meets the workshop rubric."
    • Criteria URL: Link to the workshop landing page or to MongoDB University's workshop catalog entry.
    • Skills: At minimum: MongoDB, Document Modeling, AI-Assisted Development. Add more if the team has a standard list.
    • Activity type: Workshop completion or equivalent. At least one badge_template_activity is required.
  4. Upload the badge image.
  5. Set Allow duplicate badges to true. Attendees can resubmit the schema summary multiple times; if they pass on a later attempt after a previous failure, allowing duplicates avoids 422 errors. (If your organization policy requires duplicates off, the evaluator's credly.js already treats duplicate-badge errors as success.)
  6. Save and publish the template.

Once published, copy the badge template id from the URL or the API. You'll set it as CREDLY_BADGE_TEMPLATE_ID in the evaluator environment.

Step 2: Generate an authorization token

The evaluator authenticates with Credly via HTTP Basic Auth using an organization authorization token as the username (blank password).

In the Credly admin UI:

  1. Navigate to Organization Management → Developers → Authorization Tokens.
  2. Create a new token. Give it a recognizable name (e.g., ai-coding-with-mongodb-evaluator).
  3. Grant the minimum scope: write access to badges. The token does not need read access for this use case.
  4. Copy the token value immediately. Credly does not show it again after the modal closes.
  5. Note the expiration date. Tokens expire after 180 days by default. Add a calendar reminder to rotate the token before that date.

You'll set this token as CREDLY_API_KEY in the evaluator environment.

Step 3: Configure evaluator environment

Set these variables in the evaluator's runtime environment. The exact mechanism depends on where you deploy (Lambda env vars, ECS task definition, Heroku config, Kubernetes secret, etc.):

Variable Value
CREDLY_ORGANIZATION_ID The UUID from your Credly organization.
CREDLY_BADGE_TEMPLATE_ID The UUID from the badge template you created in Step 1.
CREDLY_API_KEY The authorization token from Step 2.
GROVE_API_KEY A static Grove gateway key for the evaluator's Anthropic calls. Distinct from the per-event proxy key used by Claude Code.

Optional:

Variable Default Purpose
CREDLY_BASE_URL https://api.credly.com/v1 Override only when testing against a Credly staging environment if you have one.
ANTHROPIC_MODEL claude-opus-4-7 Override if you want to evaluate with a different model.
PORT 8080 Server listen port.

Step 4: Smoke test

Before the first event, run the evaluator end-to-end with a known-good submission and a known-bad submission.

The good submission should be a complete schema summary covering all six rubric sections with explicit reasoning. (You can generate one yourself by running the workshop's Lab 4 prompt against a properly-imported retail database.) Submit it via the frontend at ?session=test-event-001. Expected result: overall verdict pass, score 80 or higher, and a Credly badge delivered to the test email within a minute.

The bad submission should be a one-paragraph summary that names a few collections without justification. Same session id. Expected result: overall verdict needs-revision, no badge issued, per-criterion feedback explaining what was missing.

Verify in the Credly admin UI that the test badge appears under Issued Badges. Once verified, revoke the test badge so it doesn't appear on the test recipient's Credly profile.

Step 5: Token rotation

Authorization tokens expire after 180 days. Two months before expiration, generate a new token, update CREDLY_API_KEY in the evaluator environment, and verify with another smoke test before the old token expires.

The evaluator does not need to be redeployed when the token rotates if your deployment platform supports environment variable updates without redeploys. If it does require a redeploy, schedule the rotation during a known maintenance window.

Failure modes

The evaluator is designed to fail gracefully. If Credly is unreachable, the attendee still sees their pass verdict and feedback; the badge issuance is logged as failed but the response is not blocked. The DRI is expected to monitor logs for badge issuance failures and follow up with affected attendees out-of-band.

A search of the evaluator's logs for [credly] badge issuance failed returns the affected emails. If the failure was transient (network, 5xx), retrying the issuance manually via the Credly UI for those attendees is the correct remediation. If the failure was a 401, the token has been revoked or rotated without updating the env var.