Embed a Claim Button

How-To Guide: Add a credential claim button to any website using the LearnCard Embed SDK

Add a "Claim Credential" button to any webpage. When a user clicks it, a modal walks them through email verification and deposits the credential into their LearnCard wallet.

~15 min · Start here — the CLI sets up everything it needs.

The one-line version

npx @learncard/cli embed --domains https://yoursite.com

Sets up LearnCard to sign for you, registers an integration whitelisted to your origins, saves the publishable key to .env, and writes claim-button.html — a working page with the key filled in. Serve it from a whitelisted origin (not file://) and click the button.

The rest of this page is the same setup by hand.

This is for external websites that want to award credentials to visitors. If you're building an app that runs inside the LearnCard App Store, see Build an App Inside LearnCard instead.

Step 1: Get a publishable key

The button is keyed to an integration — a record that holds your allowed origins and a publishable key (pk_…). Either:

• run npx @learncard/cli embed --domains https://yoursite.com (creates it and saves PUBLISHABLE_KEY to .env), or

• in the Developer Portal open Guides → Embed Claim Button, follow the setup, and copy the key from the Embed Code tab.

Credentials claimed through the button are signed by your primary signing authority; the CLI sets one up if you don't have one.

Step 2: Add the SDK

Script Tag (CDN)

<script src="https://cdn.jsdelivr.net/npm/@learncard/embed-sdk@latest/dist/learncard.js"></script>

npm/ESM

npm install @learncard/embed-sdk

import { init } from '@learncard/embed-sdk';

Step 3: Initialize the SDK

Add a target element and call init():

<!-- Where the button should appear -->
<div id="claim-credential"></div>

<script>
    LearnCard.init({
        publishableKey: 'pk_your_key_here',
        target: '#claim-credential',
        credential: { name: 'Your Template Name' },
        partnerName: 'Your Organization Name',
    });
</script>

The credential name must match a template you created in the Developer Portal. The SDK resolves it server-side.

Step 4: Customize Branding (Optional)

LearnCard.init({
    publishableKey: 'pk_your_key_here',
    target: '#claim-credential',
    credential: { name: 'Course Completion' },
    partnerName: 'Learning Economy Academy',
    branding: {
        primaryColor: '#1F51FF', // Button + stepper color
        accentColor: '#0F3BD9', // Hover states
        partnerLogoUrl: 'https://your-org.com/logo.png',
        walletUrl: 'https://app.learncard.com',
    },
});

Step 5: Handle Success (Optional)

After claiming, the SDK opens the wallet in a new tab (deep-linked to the credential via handoffUrl) and shows a success screen. Hook into this with onSuccess:

LearnCard.init({
    publishableKey: 'pk_your_key_here',
    target: '#claim-credential',
    credential: { name: 'Course Completion' },
    onSuccess: ({ credentialId, handoffUrl }) => {
        // Runs in addition to the wallet auto-open
        document.getElementById('success-message').style.display = 'block';
    },
});

To suppress the automatic wallet redirect entirely, set branding.walletUrl: '':

LearnCard.init({
    publishableKey: 'pk_your_key_here',
    target: '#claim-credential',
    credential: { name: 'Course Completion' },
    branding: { walletUrl: '' }, // Disable auto-open
    onSuccess: ({ credentialId, handoffUrl }) => {
        // You fully control what happens next
        document.getElementById('success-message').style.display = 'block';
    },
});

Complete Example

This is the file npx @learncard/cli embed writes, with PUBLISHABLE_KEY_PLACEHOLDER replaced by your key:

<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>Claim your badge</title>
    </head>
    <body>
        <h1>Claim your badge</h1>
        <div id="claim-button"></div>
        <script src="https://cdn.jsdelivr.net/npm/@learncard/embed-sdk@latest/dist/learncard.js"></script>
        <script>
            // init renders the Claim button into #claim-button.
            LearnCard.init({
                target: '#claim-button',
                publishableKey: 'PUBLISHABLE_KEY_PLACEHOLDER',
                apiBaseUrl: 'https://network.learncard.com/api',
                // A full unsigned badge works without a named integration template.
                credential: {
                    '@context': [
                        'https://www.w3.org/ns/credentials/v2',
                        'https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json',
                        'https://ctx.learncard.com/boosts/1.0.3.json',
                    ],
                    type: ['VerifiableCredential', 'OpenBadgeCredential', 'BoostCredential'],
                    name: 'Badge Name',
                    credentialSubject: {
                        type: ['AchievementSubject'],
                        achievement: {
                            id: 'urn:uuid:552bf83b-7700-4c3a-b1ce-2d8f8ee68811',
                            type: ['Achievement'],
                            name: 'Badge Name',
                            description: 'Claimed a badge with LearnCard.',
                            criteria: { narrative: 'Clicked the Claim button.' },
                        },
                    },
                },
            });
        </script>
    </body>
</html>

Whitelisted Domains

The API only accepts claims from domains whitelisted in the Embed Code tab of your Developer Portal. Add your production domain before going live.

During local development, localhost is allowed automatically.

Troubleshooting

"This integration could not be found" Your publishableKey doesn't match an active integration. Check the key from your Developer Portal Embed Code tab and ensure your domain is whitelisted.

Credential not appearing after claim The credential lands in the user's inbox and is finalized when they open their wallet. To verify immediately, check the Developer Portal's activity tab.

Embedded claims stay claimable for 720 days by default. For transcripts, CLRs, or other sensitive learner records, pass a shorter expiresInDays (1–720) in the /inbox/claim configuration, e.g. configuration: { publishableKey, expiresInDays: 7 }. This controls how long the encrypted payload can be claimed, not the credential's own validity dates.

OTP not arriving In local dev, check your brain-service logs — OTP codes are printed there when no email provider is configured.

See Also

• Embed SDK Reference

• Connect a User's LearnCard to Your Platform — for an ongoing link instead of one-off claims

• Build an App Inside LearnCard — for apps inside LearnCard