Data Models

This page documents all data models, request/response structures, and type definitions used in the Veriglob API.

Common Response Structures

API Response (Success)

All successful API responses follow this structure:

interface APIResponse<T> {
  status: "success";
  message: string;
  data: T;
}

Example:

{
  "status": "success",
  "message": "Operation completed successfully",
  "data": {
    // Endpoint-specific data
  }
}

Error Response

All error responses follow this structure:

interface ErrorResponse {
  status: "error";
  message: string;
  error: string;
}

Example:

{
  "status": "error",
  "message": "Validation Error",
  "error": "issuer_did is required"
}

---

DID Models

CreateDIDRequest

interface CreateDIDRequest {
  public_key?: string;  // Base64-encoded Ed25519 public key (optional)
}

CreateDIDResponse

interface CreateDIDResponse {
  did: string;              // The generated did:key identifier
  public_key: string;       // Base64-encoded public key
  private_key?: string;     // Base64-encoded private key (only if generated)
}

ResolveDIDResponse

interface ResolveDIDResponse {
  did: string;              // The resolved DID
  public_key: string;       // Base64-encoded public key
}

DIDDocument

W3C-compliant DID Document structure:

interface DIDDocument {
  "@context": string[];
  id: string;                           // The DID
  verificationMethod: VerificationMethod[];
  authentication: string[];
  assertionMethod: string[];
  keyAgreement?: string[];
  capabilityInvocation?: string[];
  capabilityDelegation?: string[];
}

interface VerificationMethod {
  id: string;
  type: string;                         // "Ed25519VerificationKey2020"
  controller: string;
  publicKeyMultibase: string;
}

---

Credential Models

IssueCredentialRequest

interface IssueCredentialRequest {
  issuer_did: string;           // DID of the credential issuer
  issuer_private_key: string;   // Base64-encoded private key for signing
  subject_did: string;          // DID of the credential subject
  credential_type: string;      // Type of credential
  claims: Record<string, any>;  // Custom claims/attributes
  expiration_date?: string;     // ISO 8601 expiration date
}

IssueCredentialResponse

interface IssueCredentialResponse {
  credential_id: string;        // URN UUID of the credential
  credential: string;           // PASETO v4 credential token
  issuer: string;               // Issuer DID
  subject: string;              // Subject DID
  credential_type: string;      // Type of credential
  issued_at: string;            // ISO 8601 issuance timestamp
  expires_at?: string;          // ISO 8601 expiration timestamp
}

VerifyCredentialRequest

interface VerifyCredentialRequest {
  credential: string;           // PASETO v4 credential token
  issuer_did: string;           // Expected issuer DID
  check_revocation?: boolean;   // Check revocation status (default: false)
}

VerifyCredentialResponse

interface VerifyCredentialResponse {
  valid: boolean;               // Whether the credential is valid
  issuer?: string;              // Issuer DID (if valid)
  subject?: string;             // Subject DID (if valid)
  credential_type?: string;     // Credential type (if valid)
  claims?: Record<string, any>; // Credential claims (if valid)
  issued_at?: string;           // Issuance timestamp (if valid)
  expires_at?: string;          // Expiration timestamp (if valid)
  revoked?: boolean;            // Revocation status (if checked)
  expired?: boolean;            // Expiration status
  error?: string;               // Error message (if invalid)
}

RevokeCredentialRequest

interface RevokeCredentialRequest {
  reason?: string;              // Reason for revocation
  issuer_did: string;           // Issuer DID for authorization
}

RevokeCredentialResponse

interface RevokeCredentialResponse {
  credential_id: string;        // Revoked credential ID
  revoked: boolean;             // Always true
  revoked_at: string;           // ISO 8601 revocation timestamp
  reason?: string;              // Revocation reason
}

CheckRevocationStatusResponse

interface CheckRevocationStatusResponse {
  credential_id: string;        // Credential ID
  revoked: boolean;             // Whether credential is revoked
  revoked_at?: string;          // Revocation timestamp (if revoked)
  reason?: string;              // Revocation reason (if revoked)
}

ListCredentialsResponse

interface ListCredentialsResponse {
  credentials: CredentialSummary[];
  total: number;
}

interface CredentialSummary {
  credential_id: string;
  issuer?: string;              // Present when listing by subject
  subject?: string;             // Present when listing by issuer
  credential_type: string;
  issued_at: string;
  expires_at?: string;
  revoked: boolean;
}

---

Presentation Models

CreatePresentationRequest

interface CreatePresentationRequest {
  holder_did: string;           // DID of the presentation holder
  holder_private_key: string;   // Base64-encoded private key for signing
  credentials: string[];        // Array of PASETO v4 credential tokens
  audience: string;             // DID of the intended verifier
  nonce?: string;               // Challenge nonce from verifier
  domain?: string;              // Domain for the presentation
}

CreatePresentationResponse

interface CreatePresentationResponse {
  presentation_id: string;      // URN UUID of the presentation
  presentation: string;         // PASETO v4 presentation token
  holder: string;               // Holder DID
  audience: string;             // Audience DID
  credentials_count: number;    // Number of included credentials
  created_at: string;           // ISO 8601 creation timestamp
}

VerifyPresentationRequest

interface VerifyPresentationRequest {
  presentation: string;         // PASETO v4 presentation token
  audience: string;             // Expected audience DID
  nonce?: string;               // Expected nonce value
  verify_credentials?: boolean; // Verify contained credentials (default: true)
  check_revocation?: boolean;   // Check credential revocation (default: false)
}

VerifyPresentationResponse

interface VerifyPresentationResponse {
  valid: boolean;               // Whether the presentation is valid
  holder?: string;              // Holder DID (if valid)
  audience?: string;            // Audience DID (if valid)
  nonce_valid?: boolean;        // Whether nonce matches (if provided)
  credentials?: CredentialVerification[]; // Verification results for each credential
  created_at?: string;          // Presentation creation timestamp
  error?: string;               // Error message (if invalid)
}

interface CredentialVerification {
  valid: boolean;
  issuer: string;
  subject: string;
  credential_type: string;
  claims: Record<string, any>;
  revoked?: boolean;
  expired?: boolean;
}

---

Wallet Models

CreateWalletRequest

interface CreateWalletRequest {
  name: string;                 // Wallet name
  password: string;             // Encryption password
  description?: string;         // Optional description
}

CreateWalletResponse

interface CreateWalletResponse {
  wallet_id: string;            // Wallet identifier
  name: string;                 // Wallet name
  did: string;                  // Generated DID for the wallet
  public_key: string;           // Base64-encoded public key
  created_at: string;           // ISO 8601 creation timestamp
}

OpenWalletRequest

interface OpenWalletRequest {
  wallet_id: string;            // Wallet identifier
  password: string;             // Decryption password
}

OpenWalletResponse

interface OpenWalletResponse {
  wallet_id: string;
  name: string;
  did: string;
  public_key: string;
  private_key: string;          // Decrypted private key
  credentials: StoredCredential[];
  created_at: string;
}

interface StoredCredential {
  credential_id: string;
  credential: string;           // PASETO v4 token
  credential_type: string;
  issuer: string;
  stored_at: string;
  metadata?: Record<string, any>;
}

---

API Key Models

GenerateKeyRequest

interface GenerateKeyRequest {
  name: string;                 // Descriptive name for the key
  tier?: string;                // Subscription tier (uses account default)
}

GenerateKeyResponse

interface GenerateKeyResponse {
  key_id: string;               // Key identifier
  api_key: string;              // Full API key (shown only once)
  name: string;                 // Key name
  tier: string;                 // Rate limit tier
  rate_limit: number;           // Requests per minute
  created_at: string;           // ISO 8601 creation timestamp
  last_used_at?: string;        // Last usage timestamp
}

APIKeySummary

interface APIKeySummary {
  key_id: string;
  name: string;
  key_prefix: string;           // Masked key (e.g., "vg_live_xxxx...xxxx")
  tier: string;
  rate_limit: number;
  created_at: string;
  last_used_at?: string;
  active: boolean;
}

---

User Models

User

interface User {
  user_id: string;
  email: string;
  name?: string;
  tier: string;
  created_at: string;
  last_login_at?: string;
}

UserStats

interface UserStats {
  dids_created: number;
  credentials_issued: number;
  presentations_created: number;
  api_keys_active: number;
}

---

Auth Models

LoginRequest

interface LoginRequest {
  email: string;
  password: string;
}

LoginResponse

interface LoginResponse {
  user_id: string;
  email: string;
  name?: string;
  tier: string;
  token: string;                // JWT access token
  refresh_token: string;        // JWT refresh token
  expires_at: string;           // Token expiration timestamp
}

RegisterRequest

interface RegisterRequest {
  email: string;
  password: string;
  name?: string;
}

RegisterResponse

interface RegisterResponse {
  user_id: string;
  email: string;
  name?: string;
  tier: string;
  created_at: string;
}

LogoutRequest

interface LogoutRequest {
  token: string;                // Token to invalidate
}

---

Enums and Constants

Subscription Tiers

enum Tier {
  FREE = "free",
  BASIC = "basic",
  PRO = "pro",
  ENTERPRISE = "enterprise"
}

Rate Limits by Tier

Tier	Requests per Minute
free	10
basic	100
pro	1,000
enterprise	10,000

Common Credential Types

const CredentialTypes = [
  "VerifiableCredential",
  "EmploymentCredential",
  "EducationCredential",
  "MembershipCredential",
  "IdentityCredential",
  "AgeVerificationCredential",
  "AddressCredential",
  "ProfessionalLicenseCredential"
];

HTTP Status Codes

Code	Meaning
200	OK - Request succeeded
201	Created - Resource created
400	Bad Request - Invalid input
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
409	Conflict - Resource already exists
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error