HTTP BINDING

Request

GET /api/resource HTTP/1.1
Host: api.example.com
X-KYA-Credential: eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...
X-KYA-Token: eyJpc3MiOiJkaWQ6a2V5Ono2TWsuLi4iLCJjcmlzcCI6...

Response

HTTP/1.1 200 OK
X-KYA-Verified: true
X-KYA-Agent: did:key:z6Mk...
X-KYA-Budget-Remaining: 42

1. Header Format

Credentials transmitted via custom HTTP headers.
Base64url-encoded VC-JWT format.
CRISP tokens in separate header for budget tracking.

2. Request Flow

1. Client includes X-KYA-Credential header
2. Optional X-KYA-Token for budget-bound operations
3. Server verifies Ed25519 signature
4. Server validates delegation chain
5. Server enforces CRISP budget if present

3. Response Headers

X-KYA-Verified: Boolean verification result
X-KYA-Agent: Verified agent DID
X-KYA-Budget-Remaining: CRISP token budget after operation

4. Error Codes

401 Unauthorized
  - Missing X-KYA-Credential header
  - Invalid signature
  - Expired credential

403 Forbidden
  - Valid credential, insufficient permissions
  - CRISP budget exhausted
  - Delegation revoked

429 Too Many Requests
  - Rate limit exceeded
  - CRISP budget depleted

5. Examples

Curl

curl -H "X-KYA-Credential: eyJ..." \
     -H "X-KYA-Token: eyJ..." \
     https://api.example.com/resource

JavaScript

fetch('https://api.example.com/resource', {
  headers: {
    'X-KYA-Credential': credential,
    'X-KYA-Token': token
  }
})