How Does This Work?

First, an issuer defines one or more blue.badge.definition records to be issued:

{
    "uri": "at://did:plc:puy52u7opoy3gvrv7h7qdy76/blue.badge.definition/6XXzn32gbU",
    "cid": "bafyreifbq7wub6wfuntruagvaaivqsinxyc4mpbfagjka35v4wx7aeu3fe",
    "value": {
        "name": "Adventure Awaits!",
        "text": "You're in for an adventure! Log in for the first time to https://atproto.camp/",
        "$type": "blue.badge.definition"
    }
}

With the permission of a @handle (via OAuth), the issuer writes a blue.badge.award record to the @handle's repository. They can use the blue.badge.collection collection or their own.

The award record contains basic badge information as well as a cryptographic signature of the badge:

{
    "$type": "blue.badge.award",
    "badge": {
        "cid": "bafyreifbq7wub6wfuntruagvaaivqsinxyc4mpbfagjka35v4wx7aeu3fe",
        "description": "You\u0027re in for an adventure! Log in for the first time to https://atproto.camp/.",
        "name": "Adventure Awaits!",
        "uri": "at://did:plc:puy52u7opoy3gvrv7h7qdy76/blue.badge.definition/6XXzn32gbU"
    },
    "did": "did:plc:cbkjy5n7bk3ax2wplmtjofq2",
    "issued": "2024-08-26T22:14:02.000Z",
    "proof": {
        "k": "https://atproto.camp/.well-known/jwks.json#01J67HHM2CCKT98FE20SKPR5EA",
        "s": "2-EaPZELcvu5SL8lS863fta8moqLZcpKlrzFpn7RbUr_B37HZphJa642dJfGNM2BMZGl-YGQync-2pyhoPC4Wg=="
    }
}

That signature can be verified by applications and clients using the proof key and signature. The key is a URL to a JSON Web Key Set with the Key Identifier in the URL fragment. The signaure is created from the DAG-CBOR encoded badge record without the proof element (just the $type, did, badge, and issued elements).

Badge Image Embedding

Badges can be embedded as SVG images using the https://render.badge.blue/badge URL with the `uri` query string parameter: https://render.badge.blue/badge?uri=at://did:plc:cbkjy5n7bk3ax2wplmtjofq2/blue.badge.collection/3l2npthykb226

The rendered badge image will include the issuer handle, subject handle, and badge title.