The badge wall

Install

1. Create an API key on the Badge wall page of your dashboard.
2. Put it in your server's environment as WALL_API_KEY. It is a secret: never give it a public prefix such as NEXT_PUBLIC_ or VITE_.
3. Render the wall on your homepage, usually in the footer. That's the page directories look at.
4. Back in the dashboard, run a check. Checkout opens once we find the wall.

Next.js (App Router)

import { WallBadges } from "@distriova/badges/react";

export function Footer() {
  return (
    <footer>
      <WallBadges />
    </footer>
  );
}

WallBadges is an async Server Component. It reads WALL_API_KEY and keeps the wall for a minute before asking again.

Any other server

import { fetchWall, layoutWall, wallToHtml } from "@distriova/badges";

const wall = await fetchWall();
const html = wall ? wallToHtml(layoutWall(wall)) : "";
// print html in your footer template; every value in it is escaped

Compatible clients

The endpoint is GET /v1/wall with Authorization: Bearer sbk_live_…. It answers a signed envelope (payload, signature, keyId): Ed25519 over the exact payload text. Clients that follow the open badge-wall v1 contract can verify and render it by pointing their API URL at us and pinning our public key.

Formats and settings

• Ribbon: one gliding line of badges in your footer bar.
• Window: a small gliding window, for a narrow column under your logo.
• Theme: light, dark, or auto (uses a directory's dark badge when your visitor prefers dark).
• Attribution: a small "Badge wall by" line, always rel="nofollow", or none.

You change these in the dashboard; your code stays the same.

What the wall guarantees

• Signed. The package checks our Ed25519 signature against keys pinned in its code before reading anything. A wall changed on the way renders nothing.
• Strictly checked. Links must be https and point to the directory's own domain; images must be https; text is length-limited; a wall expires after a week at most. One bad field and the whole wall is refused.
• Plain HTML. Links, images, a few spans and one scoped style tag, all written by the package. No scripts, no HTML from our API.
• In your server's HTML. Directory checkers read the badges without running JavaScript. Motion is CSS only, pauses on hover and focus, and stops under reduced-motion settings.
• Never breaks your page. If our API is slow or down, the last good wall is kept, or nothing renders.
• Fair to directories. Each badge uses the directory's own link, rel and image. Badges a directory wants visible at all times never move.
• Visible from day one. Before your first order, the wall shows one line saying badges will appear, so you can place it and we can detect it.

Revoking a key

Revoke a key from the dashboard if it leaks. It stops working at once, and your site shows no wall until it has a new key.