Skip to main content

​
API Keys Guide

Learn how to manage API authentication using the Wacht Rust SDK. API keys allow you to securely authenticate applications and services with the Wacht API.

​
Prerequisites

Before using any API methods, you must initialize the SDK: 
use wacht::WachtClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the client with an API key
    let client = WachtClient::new("wk_live_...");

    // Now you can use the API
    Ok(())
}

​
List API Auth Apps

Get all API authentication apps in your deployment. 
use wacht::WachtClient;

let client = WachtClient::new("wk_live_...");

// Get active apps only
let apps = client.api_keys().list_api_auth_apps()
    .send()
    .await?;

for app in apps {
    println!("{} (active: {})", app.name, app.is_active);
}

​
Include Inactive Apps

use wacht::WachtClient;

let client = WachtClient::new("wk_live_...");

// Get all apps including inactive ones
let apps = client.api_keys().list_api_auth_apps()
    .include_inactive(true)
    .send()
    .await?;

​
Get API Auth App

Retrieve a specific API auth app by name. 
use wacht::WachtClient;

let client = WachtClient::new("wk_live_...");

let app = client.api_keys().get_api_auth_app("my-integration")
    .send()
    .await?;

println!("App: {} (ID: {})", app.name, app.id);

​
Create API Auth App

Create a new API authentication app with rate limiting.

​
Basic App Creation

use wacht::WachtClient;
use wacht::models::CreateApiAuthAppRequest;

let client = WachtClient::new("wk_live_...");

let app = client.api_keys().create_api_auth_app(CreateApiAuthAppRequest {
    app_slug: "my-integration".to_string(),
    name: "My Integration".to_string(),
    key_prefix: "sk_live".to_string(),
    description: Some("Integration with external service".to_string()),
    rate_limit_scheme_slug: None,
})
.send()
.await?;

println!("Created app: {}", app.id);

​
With Rate Limiting

use wacht::WachtClient;
use wacht::models::{CreateApiAuthAppRequest, RateLimit, RateLimitUnit, RateLimitMode};

let client = WachtClient::new("wk_live_...");

// First, create a rate limit scheme (not shown here, but assumed to exist)
// For example, a scheme with slug "my-rate-limit-scheme"

let app = client.api_keys().create_api_auth_app(CreateApiAuthAppRequest {
    app_slug: "my-integration-with-rate-limit".to_string(),
    name: "My Integration with Rate Limit".to_string(),
    key_prefix: "sk_live".to_string(),
    description: Some("Integration with external service and rate limits".to_string()),
    rate_limit_scheme_slug: Some("my-rate-limit-scheme".to_string()),
})
.send()
.await?;

​
Update API Auth App

Modify an existing API auth app configuration. 
use wacht::WachtClient;
use wacht::models::UpdateApiAuthAppRequest;

let client = WachtClient::new("wk_live_...");

let app = client.api_keys().update_api_auth_app(
    "my-integration",
    UpdateApiAuthAppRequest {
        name: Some("Updated Integration Name".to_string()),
        is_active: Some(false),
        ..Default::default()
    }
)
.send()
.await?;

​
Delete API Auth App

Remove an API auth app entirely. 
use wacht::WachtClient;

let client = WachtClient::new("wk_live_...");

client.api_keys().delete_api_auth_app("my-integration")
    .send()
    .await?;

​
List API Keys

Get all keys for a specific app. 
use wacht::WachtClient;

let client = WachtClient::new("wk_live_...");

// Get active keys only
let keys = client.api_keys().list_api_keys("my-integration")
    .send()
    .await?;

for key in keys {
    println!("{}: {}***{} (active: {})",
        key.name, key.key_prefix, key.key_suffix, key.is_active
    );
}

​
Include Inactive Keys

use wacht::WachtClient;

let client = WachtClient::new("wk_live_...");

let keys = client.api_keys().list_api_keys("my-integration")
    .include_inactive(true)
    .send()
    .await?;

​
Create API Key

Generate a new API key for an app.

​
Basic Key Creation

use wacht::WachtClient;
use wacht::models::CreateApiKeyRequest;

let client = WachtClient::new("wk_live_...");

let key = client.api_keys().create_api_key(
    "my-integration",
    CreateApiKeyRequest {
        name: "Production Key".to_string(),
        permissions: None,
        organization_membership_id: None,
        workspace_membership_id: None,
        expires_at: None,
        metadata: None,
    }
)
.send()
.await?;

println!("API Key: {}", key.secret); // Store this securely!

​
With Permissions and Expiration

use wacht::WachtClient;
use wacht::models::CreateApiKeyRequest;
use chrono::{Duration, Utc};

let client = WachtClient::new("wk_live_...");

let key = client.api_keys().create_api_key(
    "my-integration",
    CreateApiKeyRequest {
        name: "Production Key".to_string(),
        permissions: Some(vec![
            "users:read".to_string(),
            "orgs:read".to_string(),
        ]),
        organization_membership_id: None,
        workspace_membership_id: None,
        expires_at: Some(Utc::now() + Duration::days(365)),
        metadata: Some(serde_json::json!({"environment": "production"})),
    }
)
.send()
.await?;

println!("API Key: {}", key.secret); // Store this securely!
println!("Expires: {}", key.key.expires_at.unwrap());

​
Revoke API Key

Revoke an API key when it’s no longer needed. 
use wacht::WachtClient;
use wacht::models::RevokeApiKeyRequest;

let client = WachtClient::new("wk_live_...");

client.api_keys().revoke_api_key(RevokeApiKeyRequest {
    key_id: "key_123".to_string(),
    reason: Some("Key no longer needed".to_string()),
})
.send()
.await?;

​
Rotate API Key

Rotate an API key while maintaining the same permissions. 
use wacht::WachtClient;
use wacht::models::RotateApiKeyRequest;

let client = WachtClient::new("wk_live_...");

let new_key = client.api_keys().rotate_api_key(RotateApiKeyRequest {
    key_id: "key_123".to_string(),
})
.send()
.await?;

println!("New key: {}", new_key.secret); // Store this securely!

​
Rate Limiting

Configure rate limits for your API auth apps to control usage.

​
Rate Limit Units

use wacht::models::RateLimitUnit;

RateLimitUnit::Second  // Requests per second
RateLimitUnit::Minute  // Requests per minute
RateLimitUnit::Hour    // Requests per hour
RateLimitUnit::Day     // Requests per day

​
Rate Limit Modes

use wacht::models::RateLimitMode;

RateLimitMode::PerKey        // Limit per API key
RateLimitMode::PerIp         // Limit per IP address
RateLimitMode::PerKeyAndIp  // Limit per key and IP combination

​
Example Rate Limit Configuration

use wacht::models::{RateLimit, RateLimitUnit, RateLimitMode};

RateLimit {
    unit: RateLimitUnit::Minute,
    duration: 1,  // 1 minute
    max_requests: 100,  // 100 requests
    mode: Some(RateLimitMode::PerKey),
}

​
Builder Methods

​
ListApiAuthAppsBuilder

  • include_inactive(bool) - Include inactive apps in results

​
ListApiKeysBuilder

  • include_inactive(bool) - Include inactive keys in results

​
Request Models

​
request
CreateApiAuthAppRequest
required
​
request
UpdateApiAuthAppRequest
​
request
CreateApiKeyRequest
required
​
request
RevokeApiKeyRequest
required
​
request
RotateApiKeyRequest
required

​
Error Handling

All SDK methods return a Result<T, Error>: 
use wacht::{Error, api::api_keys};

match api_keys::get_api_auth_app("my-integration").send().await {
    Ok(app) => println!("App: {}", app.name),
    Err(Error::Api { status, message, .. }) => {
        eprintln!("API Error {}: {}", status, message);
    }
    Err(Error::Request(e)) => {
        eprintln!("Network error: {}", e);
    }
    Err(e) => {
        eprintln!("Other error: {}", e);
    }
}