API Key Credential Classes

In modern application environments, credentials are no longer used exclusively by humans. AI agents run autonomous reasoning loops and background tasks execute cron jobs, all utilizing API keys. When reviewing audit logs for compliance (such as HIPAA or SOC 2), distinguishing between a human action, an AI decision, and a background service is critical.

Volidator solves this with Structural API Key Classes.

---

The Credential Taxonomy

When you generate an API key on the Volidator platform, you assign it a specific Credential Class. This class dictates the structural prefix of the raw key token, allowing the Volidator ingestion worker to instantly route and stamp the actorType at the edge with zero database lookup latency.

Key Prefix	Credential Class	Intended Use Case
val_human_	Human	Interactive human sessions, CLI tools run directly by developers, OAuth key shares.
val_agent_	Agent	Autonomous LLM execution loops, agent frameworks (LangChain, CrewAI, AutoGen).
val_service_	Service	Microservices, background queues, cron tasks, static ETL scripts.

---

Generating Class-Specific Keys

When creating a new project key or rotating an existing key via the Management API, pass the credentialClass parameter:

curl -X POST https://api.volidator.com/v1/projects \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Consent Management System",
    "credentialClass": "agent",
    "credentialLabel": "Auto-Review Agent v2"
  }'

The response returns a class-prefixed key:

{
  "success": true,
  "project": {
    "id": "prj_live_a1b2c3",
    "apiKey": "val_agent_87f2e1a8b9c0d1e2f3a4b5c6",
    "apiKeyPrefix": "87f2e1a8",
    "credentialClass": "agent"
  }
}

---

Automatic Actor Stamping

When B2B SaaS receives an API call, it passes the authorization credentials to Volidator. Because the class is encoded in the prefix itself, Volidator’s edge ingestion pipeline automatically records the actor metadata:

• Human request (val_human_): Stamped in the audit log as actorType: "human".
• Agent request (val_agent_): Stamped in the audit log as actorType: "agent".
• Service request (val_service_): Stamped in the audit log as actorType: "service".

This makes checking actor origin instant and impossible to bypass at the ingestion layer.

---

Credential Handover Detection

A common security vulnerability is Credential Handover—when a developer mistakenly copies their human-designated key (val_human_) and drops it into an autonomous AI agent script.

Volidator automatically detects this pattern at the ingestion layer:

1. When the client-side SDK runs inside an AI agent framework (like LangChain or Vercel AI SDK), it automatically appends tracing context and encrypted rationale headers (X-Agent-Rationale).
2. If the Ingestion Worker receives a request authenticated with a val_human_ key but finds agent context headers present, it identifies a conflict.
3. Volidator flags the audit entry as credentialHandoverDetected: true and logs a security policy violation event in your dashboard audit stream.

This gives security officers immediate visibility into credential leakage without breaking the agent’s active execution loop.