Issuer Guide

This guide is for CogniPilot team members who need to issue credentials.

Private Key Security

The private key is required to sign credentials. Never commit it to Git or share it publicly. Store it securely and limit access to authorized personnel only.

Setup

Prerequisites

• Python 3.10+
• Access to the private signing key (keys/key-1-private.json)

Installation

# Clone the repository
git clone https://github.com/cognipilot/cognipilot_badges.git
cd cognipilot_badges

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Issuing a Credential

Basic Usage

Issue a credential to a recipient:

python scripts/issue_credential.py \
    achievements/community-participant.json \
    --recipient "mailto:recipient@example.com" \
    --recipient-name "Jane Doe" \
    --key keys/key-1-private.json \
    --output credentials/jane-doe-2025-01.json

Parameters

Parameter	Required	Description
achievement	Yes	Path to achievement JSON file
--recipient, -r	Yes	Recipient ID (email URI, DID, or URL)
--recipient-name	No	Display name for recipient
--key, -k	Yes	Path to private key file
--output, -o	No	Output file path (default: stdout)
--credential-id	No	Custom credential ID (default: auto-generated)

Recipient Identifiers

Recipients can be identified using:

• Email URI: mailto:user@example.com (recommended)
• DID: did:example:123456
• URL: https://example.com/users/123

Verifying Before Delivery

Always verify credentials before sending to recipients:

python scripts/verify_credential.py \
    credentials/jane-doe-2025-01.json \
    --key keys/key-1-public.json

Expected output:

✓ Credential verified successfully!
  Credential ID: https://credentials.cognipilot.org/credentials/...
  Issuer: CogniPilot
  Subject: mailto:recipient@example.com
  Achievement: CogniPilot Community Participant
  Signed: 2025-01-15T12:00:00Z

Batch Issuance

For issuing multiple credentials, create a CSV file with recipients:

email,name
alice@example.com,Alice Smith
bob@example.com,Bob Johnson

Then use a simple loop:

while IFS=, read -r email name; do
    python scripts/issue_credential.py \
        achievements/community-participant.json \
        --recipient "mailto:$email" \
        --recipient-name "$name" \
        --key keys/key-1-private.json \
        --output "credentials/${email%@*}-$(date +%Y%m).json"
done < recipients.csv

Delivering Credentials

By Email

Send the JSON credential file as an attachment or include a link to a hosted version.

Hosted Credentials

For public credentials, you can host them in the docs/credentials/ directory and they'll be available at https://credentials.cognipilot.org/credentials/.

Key Management

Rotating Keys

To rotate the signing key:

1. Generate a new keypair:

   python scripts/generate_keys.py --output-dir keys --key-id key-2
   

2. Update issuer.json to add the new key to verificationMethod array (keep old key for existing credentials)

3. Update docs/verification.md with new key information

4. Securely store the new private key

Backup

• Store private key backups in a secure, encrypted location
• Use a secrets manager for production deployments
• Document key recovery procedures

Creating New Achievements

To create a new badge type:

1. Create a new achievement JSON file in achievements/:

   cp achievements/community-participant.json achievements/new-badge.json
   

2. Update the achievement properties (id, name, description, criteria)

3. Create a documentation page in docs/badges/

4. Update docs/badges/index.md and mkdocs.yml navigation

5. Create badge image and add to docs/images/