Quickstart

This condenses the beltic-spec quickstart so you can issue and validate your first credential quickly.

What you get

A DeveloperCredential or AgentCredential filled from a template
Validation against the official JSON Schema (kept in-repo)
Clear validation results (OK, warnings, or errors)

Prerequisites

CLI - Install the Beltic CLI:

brew tap belticlabs/tap && brew install beltic
# or
curl -fsSL https://raw.githubusercontent.com/belticlabs/beltic-cli/master/install.sh | sh

JSON Schema validator (optional, for manual validation):
- AJV CLI: npm install -g ajv-cli ajv-formats
- or Python: pip install jsonschema

Spec repository (for templates):

git clone https://github.com/belticlabs/beltic-spec.git
cd beltic-spec

1) Pick a template

Developer templates (examples/developer/v1/tests/):

Individual minimal: valid-individual-minimal.json
Individual complete: valid-individual-complete.json
Org tier 1: valid-organization-tier1.json
Org tier 2: valid-organization-tier2-complete.json

Agent templates (examples/agent/v1/tests/):

Valid capability mixes plus invalid variants for negative tests.

2) Copy and edit

cp examples/developer/v1/tests/valid-individual-minimal.json my-dev-cred.json

Update key fields (legalName, entityType, credentialId, subjectDid, dates, etc.). Use ISO 8601 timestamps and fresh UUIDs.

Or use the CLI to create a developer credential:

beltic dev-init --name "Jane Developer" --entity-type individual --country US

3) Validate

AJV:

ajv validate \
  -s schemas/developer/v1/developer-credential-v1.schema.json \
  -d my-dev-cred.json

Python:

python3 scripts/validate_all.py

Focused npm scripts (from beltic-spec):

npm run validate:developer
npm run validate:agent
npm run test:conditional-rules  # developer conditional checks

4) Sign and verify (CLI)

# Generate keys
beltic keygen --alg EdDSA --out private.pem --pub public.pem

# Sign
beltic sign --key private.pem --payload my-dev-cred.json --out credential.jwt

# Verify
beltic verify --key public.pem --token credential.jwt

The CLI performs JSON Schema validation before signing unless you pass --skip-schema (not recommended outside debugging).

5) Verify in code (SDK)

import { validateDeveloperCredential, decodeToken } from '@belticlabs/kya';

// Validate credential data
const result = validateDeveloperCredential(credentialData);
if (result.valid) {
  console.log('Valid credential:', result.data.legalName);
}

// Decode a signed JWT
const decoded = decodeToken(token);
console.log(decoded.payload);

Use the same fixtures from beltic-spec/examples/* to mirror CLI behavior.

6) Test at the Airport (optional)

Verify your credentials at the Beltic Airport to see what access tier you qualify for:

beltic http-sign \
  --method POST \
  --url "https://airport.beltic.dev/api/check-in" \
  --key private.pem \
  --key-directory "https://your-agent.com/.well-known/http-message-signatures-directory" \
  --body-file credential.jwt \
  --format curl | bash

Quickstart

On this page