Credentials Overview

Beltic credentials provide a standardized way to represent verifiable identity for AI agents and their developers. This page explains the credential model, how credentials relate to each other, and how versioning works.

The Beltic Credential Model

Beltic defines two core credential types that work together:

DeveloperCredential

Represents a verified person or organization that develops AI agents.

Purpose: Establish accountability by linking agents to real-world entities with verified identities.

Contains:

• Legal identity information (name, entity type, jurisdiction)
• KYC/KYB verification results and tier level
• Risk assessment data (sanctions, PEP, adverse media screening)
• Tax and registration verification
• Compliance certifications
• Cryptographic identity (DID)

Issued to: Individual developers or organizations building AI agents

Validity: Typically 6-12 months, depending on KYB tier and use case

AgentCredential

Represents a specific AI agent instance with its technical profile and capabilities.

Purpose: Provide verifiable information about an agent's behavior, safety, and capabilities.

Contains:

• Link to DeveloperCredential (who built it)
• Technical profile (model, architecture, deployment)
• Tool capabilities with risk classifications
• Safety and robustness metrics
• Data handling and privacy policies
• Code fingerprint for integrity verification
• Compliance certifications

Issued to: AI agent instances (bots, assistants, autonomous agents)

Validity: Varies by agent lifecycle, typically 3-12 months

Credential Relationship

Every AgentCredential must reference a DeveloperCredential:

graph TD
    A[AgentCredential] -->|developerId field| B[DeveloperCredential]
    B -->|issued by| C[Issuer]
    C -->|trusted by| D[Verifier]

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

This creates a trust chain:

1. Verifier receives AgentCredential
2. Verifier checks AgentCredential signature and validity
3. Verifier fetches the linked DeveloperCredential
4. Verifier checks DeveloperCredential signature and validity
5. Verifier applies policy (KYB tier, safety scores, data categories)

Why this matters: If an agent misbehaves, you can trace it back to the verified developer. If a developer loses trust, all their agents can be immediately flagged or revoked.

Schema Versioning

Beltic credentials follow semantic versioning for schemas:

Current Versions

• DeveloperCredential v1 (developer-credential-v1.schema.json)
• AgentCredential v1 (agent-credential-v1.schema.json)

Version Format

Schemas use the format: {credential-type}-v{major}.schema.json

Major version changes when:

• Breaking changes to required fields
• Removal of existing fields
• Changes to field semantics

Minor changes are accommodated through:

• Optional field additions
• New enum values
• Extended documentation

Backward Compatibility

V1 commitment: The v1 schema is stable. New features will be added as optional fields to maintain compatibility.

Migration path: When v2 is released, platforms can:

• Accept both v1 and v2 credentials during a transition period
• Upgrade verification logic to support both schemas
• Encourage gradual migration without breaking existing credentials

Schema Locations

Credential schemas live in the beltic-spec repository:

beltic-spec/
├── schemas/
│   ├── developer/
│   │   └── v1/
│   │       └── developer-credential-v1.schema.json
│   └── agent/
│       └── v1/
│           └── agent-credential-v1.schema.json
├── examples/
│   ├── developer/v1/tests/
│   └── agent/v1/tests/
└── docs/
    ├── developer-credential-v1.md
    └── agent-credential-v1.md

Schema access:

• Repository: beltic-spec (currently private) - Request early access
• NPM package: @beltic/schemas (not yet published - early access only)
• Direct URL: Schemas available in beltic-spec repository (private, early access)

Assurance Levels

Fields in Beltic credentials can have different levels of verification assurance:

Assurance Types

Field-Level Assurance

Each credential field declares its minimum required assurance level in the schema:

{
  "legalName": {
    "type": "string",
    "description": "Legal name of the entity",
    "assurance": "beltic_verified"
  }
}

How verifiers use assurance:

• Check that field assurance meets their minimum requirements
• Apply higher trust to third_party_verified fields
• Flag self_attested fields for additional review in high-risk scenarios

Assurance Metadata

Credentials include metadata tracking which fields were verified:

{
  "verificationMetadata": {
    "lastVerified": "2025-01-15T10:00:00Z",
    "verificationLevel": "tier_2_standard",
    "verifiedFields": ["legalName", "taxId", "businessEmail"]
  }
}

Validation Philosophy

Beltic credentials use a multi-layer validation approach:

1. Schema Validation

JSON Schema Draft 2020-12 validates structure and data types:

• Required vs optional fields
• Data types (string, number, array, object)
• Format constraints (UUID, ISO 8601 dates, email)
• Enum values

Tools:

• AJV CLI: ajv validate -s schema.json -d credential.json
• Python: jsonschema.validate(credential, schema)
• SDK: validateDeveloperCredential(credential)

2. Runtime Validation

Business logic checks beyond schema:

• Date ordering: issuedDate < expirationDate
• Freshness: DeveloperCredential tier 2+ requires verification within last 90 days
• Field dependencies: If entityType is "organization", require incorporationDate
• Data consistency: If data categories include PHI, require HIPAA certification

Implemented in:

• SDK validation functions
• Issuer validation services
• Verifier policy engines

3. Conditional Rules

27 conditional validation rules for DeveloperCredential (2 tiers):

Tier 1 (Critical): 9 rules - Entity-type mismatches, sanctioned entities, prohibited statuses Tier 2 (High): 18 rules - Date consistency, screening requirements, freshness violations

See: Validation Guide for complete rule list

Credential Identifiers

Every credential has multiple identifiers:

credentialId

Format: UUID v4 Purpose: Unique identifier for this specific credential instance Example: 550e8400-e29b-41d4-a716-446655440000

subjectDid

Format: DID (Decentralized Identifier) Purpose: Identifies the subject (developer or agent) Example: did:web:developer.example.com or did:key:z6Mk...

issuerDid

Format: DID Purpose: Identifies who issued the credential Example: did:web:issuer.beltic.dev

developerId (AgentCredential only)

Format: UUID v4 (matching DeveloperCredential's credentialId) Purpose: Links agent to its developer Example: 550e8400-e29b-41d4-a716-446655440000

Media Types

Credentials are transmitted as JWS tokens with specific media types:

Why custom media types? They allow recipients to:

• Identify credential type before parsing
• Route to appropriate validation logic
• Apply type-specific policies

Next Steps