ID Wispera uses a passport/visa metaphor to model credential governance. This document explains the core concepts.
Overview
Just as a physical passport establishes identity and visas grant permission to enter countries, ID Wispera passports establish credential identity and visas define what operations are authorized.
Passport
A passport is a governed credential wrapper that provides:
Identity
- Name: Human-readable identifier
- Agent ID: Optional machine identifier
- Credential Type: What kind of secret this is
- Credential Value: The actual secret (encrypted at rest)
Authorization (Visa)
- Visa Type: Category of authorization
- Issuing Authority: Who issued this credential
- Scope: What operations are permitted
- Platforms: Where this credential is valid
Lifecycle
- Status: active, expiring, expired, revoked, suspended
- Validity Period: When the credential is usable
- Revocation Info: Why and by whom it was revoked
Delegation
- Delegation Chain: How the credential flowed from human to agent(s)
- Human Owner: The ultimately accountable person
- Tags: For organization and filtering
- Notes: Free-form documentation
- Timestamps: Creation and modification times
Passport States
┌──────────┐
│ Created │
└────┬─────┘
│
▼
┌──────────┐ ┌──────────┐
│ Active │────▶│ Expiring │
└────┬─────┘ └────┬─────┘
│ │
│ ▼
│ ┌──────────┐
│ │ Expired │
│ └──────────┘
│
▼
┌──────────┐
│ Revoked │
└──────────┘
- Active: Credential is valid and usable
- Expiring: Less than 14 days until expiration
- Expired: Past validity period
- Revoked: Permanently disabled
- Suspended: Temporarily disabled
A credential in the Expiring state still functions normally but serves as a warning to rotate before it becomes Expired.
Visa Types
See Visa Types for detailed descriptions.
| Type | Description |
|---|
access | Basic platform access |
privilege | Elevated permissions |
data | Data access rights |
compliance | Regulatory scope |
ecosystem | Cross-platform access |
Credential Types
| Type | Description | Example |
|---|
api-key | API authentication key | sk-..., AKIA... |
oauth-token | OAuth access/refresh token | ya29.a0... |
jwt | JSON Web Token | eyJhbG... |
secret | Generic secret | passwords, passphrases |
certificate | X.509 certificate | PEM/DER encoded certs |
private-key | Private key material | RSA, EC private keys |
connection-string | Database connection | mongodb://... |
mcp-credential | MCP-specific credential | MCP auth tokens |
custom | Other credential types | Any other secret |
Delegation Chain
The delegation chain tracks how a credential flows from human to agent(s):
Human Owner → Agent A → Agent B → Agent C
- Who delegated
- Who received
- When it was granted
- What scope was delegated
- When it expires
Scope can only narrow at each delegation hop — an agent cannot grant broader permissions than it was given.
Example
delegationChain: [
{
from: "[email protected]",
to: "orchestrator-agent",
grantedAt: "2024-01-15T10:00:00Z",
scope: ["read", "write"],
},
{
from: "orchestrator-agent",
to: "api-calling-agent",
grantedAt: "2024-01-15T10:05:00Z",
scope: ["read"], // Scope can only narrow
},
]
Best Practices
Following these practices helps maintain a strong security posture and clear accountability across your credential lifecycle.
- Always set a human owner for accountability
- Use expiration dates to ensure rotation
- Limit scope to the minimum required
- Add meaningful tags for organization
- Document in notes why the credential exists
- Monitor delegation depth to prevent long chains
- Review audit logs regularly
