auth.proto

Authentication schemas — Passkey/WebAuthn, API keys, and sessions

auth.proto

Dual authentication system: Passkey/WebAuthn for interactive users, API keys for headless (CI, servers, automation).

Passkey / WebAuthn

PasskeyChallenge

message PasskeyChallenge {
  bytes challenge = 1;       // Random challenge bytes
  string rp_id = 2;          // Relying party ID (domain)
  string rp_name = 3;        // Relying party display name
  bytes user_id = 4;         // User identifier
  uint32 timeout_ms = 5;     // Challenge timeout in ms
}

PasskeyCredential

message PasskeyCredential {
  bytes credential_id = 1;       // Credential identifier
  bytes public_key = 2;          // COSE public key
  bytes attestation = 3;         // Attestation object
  bytes authenticator_data = 4;
  bytes client_data_json = 5;
  bytes signature = 6;
}

Verification Flow

message PasskeyVerifyRequest {
  PasskeyCredential credential = 1;
  bytes challenge = 2;
}

message PasskeyVerifyResponse {
  bool verified = 1;
  string subject_id = 2;
  Session session = 3;       // Issued on success
}

API Keys

API keys are the primary authentication method for the Quint API.

message ApiKey {
  string id = 1;             // Key identifier
  string key_hash = 2;       // SHA-256 hash (raw key never stored)
  string owner_id = 3;       // Owner user/service ID
  repeated string scopes = 4;// Permission scopes
  string created_at = 5;     // ISO-8601
  string expires_at = 6;     // ISO-8601 (optional)
  bool revoked = 7;
}

Create API Key

message ApiKeyCreateRequest {
  string owner_id = 1;
  repeated string scopes = 2;
  string expires_at = 3;     // Optional expiration
}

message ApiKeyCreateResponse {
  string raw_key = 1;        // Returned ONCE — never stored
  ApiKey api_key = 2;
}

The raw_key is returned only once during creation. It is hashed before storage and cannot be recovered.

Verify API Key

message ApiKeyVerifyRequest {
  string raw_key = 1;        // Key to verify
}

message ApiKeyVerifyResponse {
  bool valid = 1;
  ApiKey api_key = 2;
}

Key prefix: qk_ (Quint key)

Sessions

message Session {
  string id = 1;
  string subject_id = 2;     // User or service ID
  string auth_method = 3;    // "passkey" | "api_key"
  repeated string scopes = 4;
  string issued_at = 5;
  string expires_at = 6;     // Max 24h lifetime
  bool revoked = 7;
}

Validate Session

message SessionValidateRequest {
  string session_token = 1;
}

message SessionValidateResponse {
  bool valid = 1;
  Session session = 2;
}

Sessions have a maximum 24-hour lifetime and are issued after successful authentication (either passkey or API key).