API Keys

API keys are how machine-to-machine clients authenticate with your app. Flux gives you programmatic key generation, fine-grained permission scopes, rotation, rate limiting, and per-key usage tracking — all without building any of that infrastructure yourself.

Generating a Key

Keys can be created from the API Keys dashboard or via the SDK.

use flux_sdk::Flux;

let flux = Flux::init("your-api-key");

let key = flux.api_keys().create(flux_sdk::CreateApiKeyRequest {
    org_id: org.id.clone(),
    name: "CI pipeline".into(),
    scopes: vec!["data:read".into(), "webhooks:write".into()],
    expires_at: None, // No expiry; set a timestamp to auto-expire
})?;

// key.secret is shown once — store it securely
println!("Created key: {}", key.secret);

Scoping Permissions

Each key is issued with an explicit list of permission scopes. Scopes map to operations in your app — define them in the API Keys settings.

Validate an inbound key and check its scopes:

let key_info = flux.api_keys().validate(&raw_key)?;

if !key_info.has_scope("data:read") {
    return Err(AuthError::Forbidden);
}

Python

import flux

flux.init("your-api-key")

key_info = flux.api_keys.validate(raw_key)

if not key_info.has_scope("data:read"):
    raise PermissionError("Insufficient scope")

Key Rotation

Rotate a key to issue a new secret while keeping the same metadata and scopes. The old secret stops working immediately.

let new_key = flux.api_keys().rotate(&key.id)?;
println!("New secret: {}", new_key.secret);

Rate Limiting

Set per-key rate limits when creating or updating a key. Limits are enforced server-side — validate() returns an error when the limit is exceeded.

let key = flux.api_keys().create(flux_sdk::CreateApiKeyRequest {
    org_id: org.id.clone(),
    name: "Public API client".into(),
    scopes: vec!["data:read".into()],
    rate_limit: Some(flux_sdk::RateLimit {
        requests: 1000,
        window_seconds: 60,
    }),
    expires_at: None,
})?;

Usage Tracking

Every validation call is recorded. View per-key request counts, error rates, and last-used timestamps from the API Keys dashboard or query them via the SDK:

let usage = flux.api_keys().get_usage(&key.id)?;
println!("Requests this month: {}", usage.requests_current_period);

Next Steps