Struct ApiKeyManagerV0 

pub struct ApiKeyManagerV0 { /* private fields */ }

ApiKeyManager is storable object used to generate and verify API keys. It contains immutable config data necessary to operate. It does NOT contain ANY sensitive data.

Implementations

impl ApiKeyManagerV0

Auto-generated by derive_getters::Getters.

pub fn hasher(&self) -> &KeyHasher

Get field hasher from instance of ApiKeyManagerV0.

impl ApiKeyManagerV0

pub fn init( prefix: impl Into<String>, config: KeyConfig, hash_config: HashConfig, expiry_grace_period: Duration, ) -> Result<Self, InitError>

pub fn init_default_config(prefix: impl Into<String>) -> Result<Self, InitError>

pub fn init_high_security_config( prefix: impl Into<String>, ) -> Result<Self, InitError>

pub fn generate( &self, environment: impl Into<Environment>, ) -> Result<ApiKey<Hash>>

Generates a new API key for the specified environment.

The generated key includes a checksum (if enabled) for fast DoS protection.

Example

let key = manager.generate(Environment::production())?;
println!("Key: {}", key.key().expose_secret());

pub fn generate_with_expiry( &self, environment: impl Into<Environment>, expiry: DateTime<Utc>, ) -> Result<ApiKey<Hash>>

Generates a new API key with an expiration timestamp.

The expiration is embedded in the key itself, making it stateless. Keys are automatically rejected after the expiry time without database lookups.

Use Cases

• Trial keys (7-30 days)
• Temporary partner access
• Time-limited API access

Example

// Create a 7-day trial key
let expiry = Utc::now() + Duration::days(7);
let key = manager.generate_with_expiry(Environment::production(), expiry)?;

pub fn verify( &self, key: &SecureString, stored_hash: impl AsRef<str>, ) -> Result<KeyStatus>

Verifies an API key against a stored hash.

Returns KeyStatus indicating whether the key is valid or invalid.

Parameters

• key - The API key to verify
• stored_hash - The Argon2 hash stored in your database
• expiry_grace_period - Optional grace period duration after expiry.
  • None: Skip expiry validation (all keys treated as non-expired)
  • Some(Duration::ZERO): Strict expiry check (no grace period)
  • Some(duration): Key remains valid for duration after its expiry time

The grace period protects against clock skew issues. Once a key expires beyond the grace period, it stays expired even if the system clock goes backwards.

Security Flow

1. Checksum validation (if enabled): Rejects invalid keys in ~20μs
2. Argon2 verification: Verifies hash for valid checksums (~300ms)
3. Expiry check: Returns Invalid if expired beyond grace period

Returns

• KeyStatus::Valid - Key is valid and not expired
• KeyStatus::Invalid - Key is invalid (wrong key, hash mismatch, checksum failed, or expired)

Note on Revocation

This method does NOT check revocation status. To implement key revocation:

1. Mark the hash as revoked in your database
2. Check revocation status before calling this method
3. Only call verify() for non-revoked hashes

Example

match manager.verify(key.key(), key.hash())? {
    KeyStatus::Valid => { /* grant access */ },
    KeyStatus::Invalid => { /* reject - wrong key or expired */ },
}

pub fn verify_checksum(&self, key: &SecureString) -> Result<bool>

Trait Implementations

impl Clone for ApiKeyManagerV0

fn clone(&self) -> ApiKeyManagerV0

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.