Core Concepts

This page introduces the core concepts you need to understand FACT credentials. If you're new to Verifiable Credentials or Decentralized Identifiers, start here.

Credentials 101

What is a Verifiable Credential?

A Verifiable Credential (VC) is a tamper-evident credential that can be cryptographically verified. Think of it like a digital version of a physical credential (driver's license, diploma, business license) but with these advantages:

• Cryptographically signed - You can verify who issued it
• Tamper-evident - Any modification breaks the signature
• Machine-readable - Software can automatically verify it
• Portable - Works across different platforms and systems
• Revocable - Issuer can invalidate it if needed

In FACT, we use VCs to represent two types of credentials:

DeveloperCredential vs AgentCredential

DeveloperCredential represents a verified person or organization:

• Contains identity information (name, entity type, jurisdiction)
• Includes KYC/KYB verification results
• Tracks compliance certifications (HIPAA, SOC2, etc.)
• Has risk assessment data (sanctions screening, PEP checks)
• Organized by KYB tiers (tier 1, 2, or 3)

AgentCredential represents a specific AI agent:

• Links to a DeveloperCredential (who built it)
• Contains technical profile (model, architecture, deployment)
• Lists tool capabilities and risk levels
• Includes safety scores (harm refusal, prompt injection, PII leakage)
• Tracks data handling policies and compliance

Relationship: Every AgentCredential must link to a DeveloperCredential. This creates a trust chain where you can verify both the agent and its creator.

Trust Chain Concept

A trust chain connects an agent back to a verified developer:

graph LR
    A[Agent] -->|links to| B[DeveloperCredential]
    B -->|issued by| C[Issuer]
    C -->|trusted by| D[Verifier/Platform]

    style A fill:#e1f5ff
    style B fill:#ffe1e1
    style C fill:#e1ffe1
    style D fill:#f5e1ff

When a platform verifies an agent:

1. Check the AgentCredential signature
2. Verify the linked DeveloperCredential
3. Check if both credentials are still valid (not expired/revoked)
4. Apply policy checks (KYB tier, safety scores, data categories)

Why trust chains matter: They provide accountability. If an agent misbehaves, you can trace it back to the verified developer and revoke credentials if needed.

Cryptographic Identity

DIDs Explained

A DID (Decentralized Identifier) is a globally unique identifier that doesn't depend on any central authority. Think of it like an email address, but you own and control it completely.

DID format: did:method:identifier

Examples:

• did:web:example.com - Controlled via your website
• did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK - Cryptographic key-based
• did:ion:EiDahaOGH-liLLdDtTxEAdc8i-cfCz-WUcQdRJheMVNn3A - Decentralized network-based

Why DIDs? They allow you to have a stable, verifiable identity without depending on centralized providers like Google or Facebook.

In FACT credentials:

• subjectDid - The entity the credential is about (developer or agent)
• issuerDid - The entity that issued the credential (Beltic or another issuer)

Signing vs Verification

Signing is creating a cryptographic proof that you issued a credential:

1. You have a private key (keep secret!)
2. You create a credential (JSON document)
3. You sign it with your private key
4. The result is a JWS token (JSON Web Signature)

Verification is checking that proof:

1. Someone gives you a JWS token
2. You extract the public key (from the issuer's DID)
3. You verify the signature matches
4. You check the credential hasn't been tampered with

Analogy: Signing is like putting your official seal on a document. Verification is like checking that the seal is authentic and hasn't been broken.

Supported Algorithms

FACT supports two signature algorithms:

Both provide strong security. EdDSA is generally faster and more modern, while ES256 is widely supported in enterprise environments.

Lifecycle

Issuance

How credentials are created and signed:

stateDiagram-v2
    [*] --> Created: Developer submits manifest
    Created --> Validated: Issuer validates identity
    Validated --> Signed: Issuer signs credential
    Signed --> Issued: Credential delivered
    Issued --> [*]

1. Manifest submission - Developer provides information (name, entity type, etc.)
2. Verification - Issuer performs KYC/KYB checks
3. Signing - Issuer signs the credential with their private key
4. Delivery - Developer receives a JWS token

Verification

How credentials are checked by platforms:

7-step verification process:

1. Parse - Decode the JWS token
2. Key Resolution - Find the issuer's public key
3. Signature - Verify the cryptographic signature
4. Claims - Check JWT claims (issuer, expiration, etc.)
5. Schema - Validate against JSON schema
6. Status - Check if revoked or suspended
7. Policy - Apply local policies (KYB tier, safety scores)

If all steps pass, the credential is valid and can be trusted.

Revocation (High-Level)

Credentials can be revoked or suspended:

• Revoked - Permanently invalid (agent compromised, developer violated terms)
• Suspended - Temporarily invalid (pending investigation, payment issue)

How it works: Issuers maintain a Status List (bitstring) that tracks revocation status. Verifiers check this list before trusting a credential.

Why revocation matters: It allows issuers to invalidate compromised or problematic credentials without waiting for expiration.

Key Terms Glossary

Issuer

The entity that creates and signs credentials. In FACT, this is typically Beltic or another trusted credential issuer.

Subject

The entity the credential is about. For DeveloperCredential, this is the developer. For AgentCredential, this is the agent.

Verifier

The platform or application that checks credentials before granting access or trust. Also called a "relying party."

Fingerprint

A SHA256 hash of an agent's codebase that provides a unique identifier for that specific version. If the code changes, the fingerprint changes.

Example: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Manifest

A structured document that developers submit to request a credential. It contains all the information needed to issue a DeveloperCredential or AgentCredential.

Location: Created locally using the Beltic CLI init command or manually from templates.

KYB Tier

The level of identity verification for a developer:

• Tier 1 (Basic) - Legal name, entity type, basic info
• Tier 2 (Standard) - Enhanced verification with screening checks
• Tier 3 (Enhanced) - Full due diligence for high-risk use cases

Higher tiers are required for agents that process sensitive data or perform financial transactions.

Assurance Level

How a field's value was verified:

• self_attested - Developer provided, not independently verified
• beltic_verified - Beltic performed verification
• third_party_verified - External verifier (e.g., credit bureau, tax authority)

Higher assurance levels mean higher confidence in the data.

JWT (JSON Web Token)

A compact, URL-safe format for transmitting JSON data. FACT credentials are delivered as JWTs with an additional signature (JWS).

Structure: header.payload.signature

Example:

eyJhbGciOiJFZERTQSIsInR5cCI6ImFwcGxpY2F0aW9uL2JlbHRpYy1kZXZlbG9wZXIrand0In0.
eyJpc3MiOiJkaWQ6d2ViOmlzc3Vlci5iZWx0aWMuZGV2Iiwic3ViIjoiZGlkOmtleTp6Nk1r...
7K7h3xZ9vB8d2M5YqN4pR6tF1sG3jK9nL2qW8eT5vC1xA4yH6mP9rU0zX3

Status List 2021

A W3C standard for tracking credential revocation status using compressed bistrings. Each credential has an index in the list; if the bit is set, the credential is revoked.

Trust Policy

Rules that verifiers apply when checking credentials. Examples:

• Minimum KYB tier (e.g., require tier 2 for financial agents)
• Minimum safety scores (e.g., require 80+ for prompt injection)
• Prohibited data categories (e.g., reject agents that process PHI)

Policies let verifiers enforce their own risk tolerance while accepting any issuer's credentials.

Visual: Complete Flow

sequenceDiagram
    participant D as Developer
    participant I as Issuer
    participant A as Agent
    participant P as Platform

    D->>I: Submit manifest (KYC/KYB)
    I->>I: Verify identity
    I->>D: Issue DeveloperCredential

    D->>D: Build agent
    D->>I: Submit agent manifest
    I->>I: Evaluate agent safety
    I->>D: Issue AgentCredential (links to DeveloperCredential)

    D->>A: Deploy agent with credentials
    A->>P: Present AgentCredential at checkout
    P->>P: Verify trust chain (agent + developer)
    P->>P: Apply policy (KYB tier, safety scores)
    P->>A: Grant or deny access

Next Steps

Now that you understand the core concepts, you're ready to dive deeper:

Additional Resources

• W3C Verifiable Credentials Data Model
• W3C Decentralized Identifiers
• JOSE (JSON Object Signing and Encryption)
• Status List 2021