Credential Lifecycle

Beltic credentials follow a complete lifecycle from initial creation through eventual expiration or revocation. This page covers each stage of the credential lifecycle and the workflows involved.

Lifecycle Stages

stateDiagram-v2
    [*] --> Created: Developer submits manifest
    Created --> Validated: Identity verification
    Validated --> Evaluated: Safety/KYC checks
    Evaluated --> Signed: Credential signing
    Signed --> Issued: Credential delivered
    Issued --> Active: In production use
    Active --> Updated: Periodic updates
    Updated --> Active: New version issued
    Active --> Suspended: Temporary revocation
    Suspended --> Active: Issue resolved
    Active --> Revoked: Permanent revocation
    Suspended --> Revoked: Escalation
    Active --> Expired: Expiration date reached
    Revoked --> [*]
    Expired --> [*]

1. Creation

Manifest Submission

Developers create an agent manifest containing all required fields:

For DeveloperCredential:

{
  "legalName": "Aurora Labs Inc.",
  "entityType": "corporation",
  "incorporationJurisdiction": {"country": "US", "region": "CA"},
  "businessEmail": "ops@auroralabs.ai",
  "kybTier": "tier_2_standard",
  ...
}

For AgentCredential:

{
  "agentName": "Aurora Refund Guide",
  "agentVersion": "2.3.0",
  "primaryModelProvider": "Anthropic",
  "primaryModelFamily": "Claude-3 Opus",
  "dataCategoriesProcessed": ["pii", "financial"],
  "toolsList": [...],
  ...
}

Submission methods:

• CLI: beltic init (generates manifest interactively)
• Web form: Upload manifest or fill in UI
• API: POST to credential issuance endpoint

Initial Validation

The manifest undergoes initial validation:

1. Schema validation - Check against JSON Schema
2. Required fields - Ensure all required fields present
3. Format validation - Verify dates, UUIDs, DIDs, etc.
4. Consistency checks - Cross-field validation rules

Validation errors stop the process - Developer receives specific error messages and must fix issues.

2. Verification & Evaluation

DeveloperCredential Verification

Tier 1 (Basic):

• Verify legal name matches business registration
• Confirm entity type
• Verify email and website ownership

Tier 2 (Standard):

• All Tier 1 checks
• Tax ID verification with tax authority
• Sanctions screening (OFAC, UN, EU lists)
• PEP (Politically Exposed Person) screening
• Adverse media screening
• Freshness: Last verified within 90 days

Tier 3 (Enhanced):

• All Tier 2 checks
• Ultimate Beneficial Owner (UBO) identification
• UBO KYC for all beneficial owners with 25%+ ownership
• Enhanced due diligence for high-risk jurisdictions
• Ongoing monitoring

Verification Timeline:

• Tier 1: 1-2 business days
• Tier 2: 3-5 business days
• Tier 3: 1-2 weeks

AgentCredential Evaluation

Safety Testing:

Beltic runs 4 core evaluations:

1. Harmful Content Refusal - Test with harmful prompts (self-harm, hate, violence)
2. Prompt Injection Robustness - Test jailbreak resistance
3. Tool Abuse Robustness - Test unauthorized tool usage
4. PII Leakage Robustness - Test privacy protection

Each test produces:

• Attack Success Rate (ASR): % of successful attacks
• Robustness Score: 100 - ASR
• Benchmark metadata: Name, version, date, assurance source

Technical Verification:

• Code fingerprint generation (SHA256 hash)
• Tool capability audit
• Data location verification
• Compliance certification validation

Evaluation Timeline: 2-5 business days depending on agent complexity

3. Signing & Issuance

Credential Signing

Once verified, the issuer signs the credential:

JWT Structure:

header.payload.signature

Header:

{
  "alg": "EdDSA",
  "typ": "application/beltic-developer+jwt",  // or beltic-agent+jwt
  "kid": "did:web:beltic.com#key-1"
}

Payload (JWT Claims):

{
  "iss": "did:web:beltic.com",           // Issuer DID
  "sub": "did:web:auroralabs.ai",        // Subject DID
  "jti": "d7aa92c7-...",                 // Credential ID
  "iat": 1699876800,                     // Issued at (Unix timestamp)
  "nbf": 1699876800,                     // Not before
  "exp": 1731412800,                     // Expiration
  "vc": {                                // Full credential object
    "legalName": "Aurora Labs Inc.",
    ...
  }
}

Signature:

• Algorithm: EdDSA (Ed25519) or ES256 (P-256)
• Private key: Issuer's signing key
• Verification: Public key from issuer DID document

Credential Delivery

Signed credentials are delivered to the developer:

Delivery methods:

• Download JWS token file
• API response with token
• Email with secure download link

Developer receives:

• JWS token (the signed credential)
• Public credential ID
• Expiration date
• Revocation check URL

4. Verification

7-Step Verification Process

When a platform receives a credential, it performs 7 verification steps:

graph TD
    A[Receive JWS Token] --> B[1. Parse JWT]
    B --> C[2. Key Resolution]
    C --> D[3. Signature Verification]
    D --> E[4. Claims Validation]
    E --> F[5. Schema Validation]
    F --> G[6. Status Check]
    G --> H[7. Policy Enforcement]
    H --> I{Pass?}
    I -->|Yes| J[Accept Credential]
    I -->|No| K[Reject Credential]

Step 1: Parse

Decode the JWS token into header, payload, and signature:

const [headerB64, payloadB64, signatureB64] = token.split('.');
const header = JSON.parse(base64Decode(headerB64));
const payload = JSON.parse(base64Decode(payloadB64));

Step 2: Key Resolution

Resolve the issuer's public key from their DID:

const issuerDid = payload.iss;
const didDocument = await resolveDid(issuerDid);
const publicKey = didDocument.verificationMethod.find(
  vm => vm.id === header.kid
).publicKeyJwk;

Step 3: Signature Verification

Verify the cryptographic signature:

const isValid = await verifySignature(
  `${headerB64}.${payloadB64}`,
  signatureB64,
  publicKey,
  header.alg
);

Failure: Signature invalid - credential tampered or forged

Step 4: Claims Validation

Check JWT claims:

const now = Math.floor(Date.now() / 1000);

// Not yet valid
if (payload.nbf && payload.nbf > now) {
  throw new Error('Credential not yet valid');
}

// Expired
if (payload.exp && payload.exp < now) {
  throw new Error('Credential expired');
}

// Issuer check
if (payload.iss !== expectedIssuer) {
  throw new Error('Untrusted issuer');
}

Step 5: Schema Validation

Validate the credential object against JSON Schema:

const credential = payload.vc;
const schema = getSchema(header.typ); // developer or agent schema

const result = validateAgainstSchema(credential, schema);
if (!result.valid) {
  throw new Error(`Schema validation failed: ${result.errors}`);
}

Step 6: Status Check

Check if the credential has been revoked:

Using Status List 2021:

const statusEntry = credential.credentialStatus;
const statusListUrl = statusEntry.statusListCredential;
const statusIndex = statusEntry.statusListIndex;

// Fetch status list (cached)
const statusList = await fetchStatusList(statusListUrl);

// Check bit at index
const isRevoked = isBitSet(statusList.bitstring, statusIndex);
if (isRevoked) {
  throw new Error('Credential has been revoked');
}

Step 7: Policy Enforcement

Apply local policies:

For DeveloperCredentials:

if (credential.kybTier < 'tier_2_standard') {
  throw new Error('Minimum KYB tier 2 required');
}

if (credential.sanctionsScreeningStatus !== 'clear') {
  throw new Error('Sanctions screening must be clear');
}

if (credential.overallRiskRating === 'high') {
  throw new Error('High-risk developers not accepted');
}

For AgentCredentials:

if (credential.harmfulContentRefusalScore < 80) {
  throw new Error('Minimum safety score 80 required');
}

if (credential.dataCategoriesProcessed.includes('health_phi')
    && !credential.complianceCertifications.includes('hipaa')) {
  throw new Error('HIPAA certification required for PHI processing');
}

// Check trust chain
await verifyAgentTrustChain(agentCredential, {
  minKybTier: 'tier_2',
  minSafetyScores: {
    harmfulContent: 80,
    promptInjection: 75,
    toolAbuse: 80,
    piiLeakage: 85
  }
});

Verification Result

If all 7 steps pass:

return {
  valid: true,
  credential: credential,
  issuer: payload.iss,
  subject: payload.sub,
  issuedAt: new Date(payload.iat * 1000),
  expiresAt: new Date(payload.exp * 1000)
};

5. Updates & Rotation

When to Update

Credentials should be updated when:

DeveloperCredential:

• KYB information changes (legal name, jurisdiction, entity type)
• Contact information updates
• KYB tier upgrade
• Annual refresh for tier 2+ (freshness requirement)
• Compliance certification obtained

AgentCredential:

• Agent version update (major/minor/patch)
• Safety evaluation refresh
• Tools added/removed
• Model or architecture changes
• Data handling policy changes

Update Process

1. Submit updated manifest with changed fields
2. Differential verification - Only verify changed fields
3. Issue new credential with new credentialId and issuanceDate
4. Gradual rollout - Old credential remains valid during transition period
5. Deprecate old credential - Mark old credential as suspended or allow expiration

Backward compatibility: Verifiers should accept both old and new credentials during transition.

Key Rotation

If signing keys are compromised:

1. Issuer rotates keys - Generate new key pair, update DID document
2. Re-sign active credentials - All active credentials re-signed with new key
3. Update DID document - New key becomes primary, old key kept for verification
4. Grace period - Both old and new signatures valid during transition
5. Revoke old key - After grace period, remove old key from DID document

6. Suspension

Reasons for Suspension

Credentials can be temporarily suspended:

DeveloperCredential:

• Pending investigation of policy violation
• Payment or billing issue
• Verification data expiration (tier 2+ freshness)
• Requested by developer (security concern)

AgentCredential:

• Developer credential suspended (cascading)
• Safety issue reported, under investigation
• Compliance violation investigation
• Temporary deployment issue

Suspension Process

1. Issuer updates status list - Set bit at credential's index
2. Status propagates - Verifiers check status before accepting
3. Developer notified - Email with reason and remediation steps
4. Grace period - Existing sessions may complete (configurable)
5. Access blocked - New requests rejected by verifiers

Reversal: Once issue resolved, clear status bit and notify verifiers.

7. Revocation

Reasons for Revocation

Permanent revocation occurs when:

DeveloperCredential:

• Terms of service violation
• Fraudulent information discovered
• Security breach or key compromise
• Sanctions match or prohibited status
• Developer requests closure

AgentCredential:

• Developer credential revoked (cascading)
• Critical safety failure in production
• Agent misused for prohibited purposes
• Code fingerprint mismatch (tampering)
• Agent retired by developer

Revocation Process

1. Issuer sets revocation bit in Status List 2021
2. Verifiers reject credential - All subsequent verification attempts fail
3. Developer notified - Reason for revocation provided
4. Cascading revocation - If developer revoked, all their agent credentials revoked
5. Permanent record - Revocation logged for audit trail

Non-reversible: Unlike suspension, revocation is permanent. Developer must apply for new credential.

Status List 2021 Mechanism

Bitstring encoding:

Credential ID -> Index -> Bit in compressed bitstring

Status values:

• Bit = 0: Active
• Bit = 1: Revoked or Suspended

Checking status:

// Fetch compressed bitstring (cached with TTL)
const response = await fetch(credential.credentialStatus.statusListCredential);
const statusList = await response.json();

// Decompress (gzip + base64)
const bitstring = decompressBitstring(statusList.encodedList);

// Check bit
const index = credential.credentialStatus.statusListIndex;
const isRevoked = (bitstring[Math.floor(index / 8)] >> (index % 8)) & 1;

8. Expiration

Expiration Handling

All credentials have an expiration date (expirationDate or JWT exp claim):

Typical validity periods:

• DeveloperCredential Tier 1: 1 year
• DeveloperCredential Tier 2: 6 months
• DeveloperCredential Tier 3: 3 months (with continuous monitoring)
• AgentCredential: 6 months

Before expiration:

• 30 days: Email reminder to renew
• 14 days: Second reminder
• 7 days: Final warning
• Expiration: Credential no longer valid

After expiration:

• Verifiers reject credential (JWT exp check fails)
• Developer must submit new manifest for renewal
• No automatic renewal (requires fresh verification)

Best Practices

For Developers

1. Monitor expiration dates - Set calendar reminders 30+ days before expiration
2. Test updates in staging - Verify new credentials work before production rollout
3. Maintain backup credentials - Have overlapping validity periods during transitions
4. Respond to suspension quickly - Address issues immediately to restore access
5. Keep contact info current - Ensure you receive notifications

For Verifiers

1. Always check status - Don't skip revocation checking for performance
2. Cache status lists - Use short TTL (5-15 minutes) to balance freshness and performance
3. Implement graceful degradation - If status service is down, apply risk-based policy
4. Log all verifications - Maintain audit trail of accepted/rejected credentials
5. Define clear policies - Document minimum KYB tiers, safety scores, and data categories

For Issuers

1. Minimize credential lifetime - Shorter validity = less revocation burden
2. Automate renewal reminders - Email developers well in advance
3. Publish SLOs - Set expectations for verification and issuance timelines
4. Monitor status list size - Optimize bitstring compression as list grows
5. Provide clear revocation reasons - Help developers understand and remediate

Next Steps