> ## Documentation Index
> Fetch the complete documentation index at: https://quintsecurity.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```protobuf theme={null}
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

```protobuf theme={null}
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

```protobuf theme={null}
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.

```protobuf theme={null}
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

```protobuf theme={null}
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;
}
```

<Warning>
  The `raw_key` is returned only once during creation. It is hashed before storage and cannot be recovered.
</Warning>

### Verify API Key

```protobuf theme={null}
message ApiKeyVerifyRequest {
  string raw_key = 1;        // Key to verify
}

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

**Key prefix:** `qk_` (Quint key)

## Sessions

```protobuf theme={null}
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

```protobuf theme={null}
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).