Build a learning application with Connect

Connect hosts and runs courses and evaluates learning evidence against its skill graph. Your application owns its interface, enrollments, assessments, and progress records. Read Connect's skill projections rather than calculating a second mastery score in your application.

Connect manages hosted course storage. Your application does not need its own R2 credentials, a shared identity provider, or a product-specific service credential. Keep your Connect API key on your server. Give the learner only the full tokenized launch URL returned by Connect.

Configure a public API key

A workspace owner or admin creates a key under Integrations → API Keys. Choose public_api. For skills integration, select the required permissions and supply a stable learning system ID such as learning-app. Creating the key registers a new learning application if that ID does not already exist in this workspace. Reuse the ID when creating replacement keys. A disabled system cannot be reactivated by creating a key.

Permissions do not upgrade your subscription. Existing keys keep their stored grants; paid checks still apply. Public keys require an explicit learning-system binding for learner projections, evidence submission, and alignment validation or writes; missing bindings can return CLIENT_SYSTEM_SCOPE_DENIED. The cale:graph:read permission does not itself require a learning-system binding. Paid entitlements remain a separate requirement.

Use Authorization: Bearer <CONNECT_API_KEY> or X-API-Key: <CONNECT_API_KEY> on server requests. The public API base is https://api.allureconnect.com/v1. A separately provisioned test deployment uses its own base ending in /api/v1.

Check GET /keys/me for effective permissions and system bindings, then GET /cale/capabilities for contract version and limits. TEST credentials are blocked from /graph, /capability, /skills, /cale, and /xapi under both /api/v1 and /v1, returning HTTP 403 with TEST_MODE_UNSUPPORTED; use an approved isolated development environment for this acceptance path. A LIVE-mode key in an isolated environment does not give access to Connect production.

Deliver a course

1. Upload and process a real SCORM package using the package workflow.
2. Your server calls POST /packages/{packageId}/launch with a stable application learner ID in user_id.
3. Store the returned session ID against that learner's enrollment. Embed the entire returned launch_url, including its token. Do not reconstruct the URL or expose your API key.
4. Preserve the session when resuming. Use the session API for progress reconciliation and the webhook guide for completion delivery. Verify signatures over the raw request bytes and deduplicate delivery IDs before changing enrollment records.

Connect learning evidence to skills

1. Discover GET /cale/frameworks and framework skills, or resolve existing references with POST /cale/skills/resolve. Persist Connect skill IDs and versions.
2. Align an immutable resource version using POST /cale/alignments/validate, then PUT /cale/alignments/{alignmentId}. Validation is preflight, not a signed receipt. Follow the OpenAPI concurrency and idempotency headers for the write and verify the issued receipt against Connect's published JWKS. Pin the trusted deployment's JWKS location; require the documented ES256 algorithm, receipt type, and signing key ID. Validate the documented claims against your expected tenant, learning system, immutable resource/version/checksum, alignment ID/revision, skill versions, graph revision/checksum, contract and policy revisions, and issue/expiry times. A valid signature alone does not authorize a different resource or tenant. Follow the deployed receipt contract rather than assuming a generic identity-token issuer/audience format.
3. Submit POST /cale/evidence/batch with { clientSystemId, items }. Each item requires a stable evidenceId, subject: { clientSystemId, subjectRef }, skillId, kind, and ISO occurredAt. For assessment evidence, include the measured scoreScaled between 0 and 1; the wire schema permits omission, but an unscored assessment is quarantined as ASSESSMENT_NEEDS_SCORE and does not establish proficiency. Preserve the original payload when retrying. Check each item's disposition; a successful HTTP response does not mean every item was accepted.
4. Read POST /cale/learner-skills/query to display Connect's resulting state. Respect observedAt and validUntil; expired cached projections must not continue to appear current.

Inspect quarantined item dispositions: INVALID_ASSESSMENT_SCORE requires correcting the measured input; ASSESSMENT_OUT_OF_ORDER retains an older assessment for reconciliation without updating current proficiency. A duplicate response does not turn a previously quarantined item into accepted evidence. Retrying the original ID and identical payload returns duplicate / IDEMPOTENT_REPLAY; changing a score under that ID returns rejected / EVIDENCE_ID_CONFLICT. Submit a corrected assessment with a new evidenceId and inspect its disposition. An out-of-order event needs reconciliation; a new ID alone does not make its timestamp current.

Completion alone is not verified mastery. Submit the assessment evidence actually collected; do not invent scores, timestamps, or approval evidence. Monetary Value outputs are modeled estimates even when they use measured inputs.

Scope of the current public contract

Graph discovery, alignments, evidence intake, and learner projections support scoped public keys. Aggregate coverage is available at GET /capability/coverage, subject to its existing entitlement and query contract.

Role configuration, the /graph/value/* routes, Value history, and Evidence Studio contribution revocation are not yet a complete public-key workflow. Do not switch an ordinary integration to internal_product or directly access the backend to fill these gaps. Keep these features unavailable in a reference application until a supported public contract and acceptance evidence exist.

The reference application acceptance must prove both SCORM standards, suspend/resume, signed completion and persisted application progress, assessment evidence into Connect and skill state back out, duplicate handling, wrong-tenant/system denial, and correction behavior supported by the deployed contract. For revocation, verify an explicit unavailable or denied outcome in the current public client; do not simulate a successful revocation. The complete showcase remains gated until a supported public revocation contract is implemented and its effect on Connect skill state is verified. Passing an HTTP health check alone does not establish that chain.

Paid feature access

Credential permissions and workspace entitlements are separate requirements. Granting a key a CALE permission does not purchase or unlock that feature. The API checks the workspace entitlement on each protected request, including requests using service credentials.

A wrong-plan request returns HTTP 402 with GRAPH_TIER_REQUIRED before the feature handler reads or writes data. Existing contracted entitlements and subscription grace periods still apply. Subscription status is synchronized into workspace entitlements; this is not a real-time Stripe charge check. Ordinary package delivery and session APIs retain their existing access rules.