Skip to main content

​
Organizations API Guide

Learn how to manage organizations using the Wacht Rust SDK.

​
Prerequisites

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize from environment variables
    // Requires: WACHT_API_KEY and WACHT_FRONTEND_HOST
    init_from_env().await?;

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

​
List Organizations

Retrieve a paginated list of organizations from your deployment.

​
Basic List

use wacht::api::organizations;

// Fetch all organizations (default pagination)
let orgs = organizations::fetch_organizations()
    .send()
    .await?;

println!("Total organizations: {}", orgs.data.len());
for org in orgs.data {
    println!("{} ({} members)", org.name, org.members_count);
}

​
With Pagination and Filters

use wacht::api::organizations;

// Fetch organizations with builder options
let orgs = organizations::fetch_organizations()
    .limit(50)
    .offset(0)
    .search("acme")
    .sort_key("created_at")
    .sort_order("desc")
    .send()
    .await?;

println!("Has more: {}", orgs.has_more);

​
Builder Methods

  • limit(i32) - Number of results to return (max 100)
  • offset(i32) - Number of results to skip
  • search(&str) - Search query to filter results
  • sort_key(&str) - Field to sort by
  • sort_order(&str) - Sort order (“asc” or “desc”)

​
Get Organization Details

Retrieve complete information about an organization. 
use wacht::api::organizations;

let details = organizations::fetch_organization_details("org_123")
    .send()
    .await?;

println!("Organization: {}", details.name);
println!("Description: {:?}", details.description);
println!("Members: {}", details.members_count);
println!("Created: {}", details.created_at);

​
Create Organization

Create a new organization in your deployment.

​
Basic Organization Creation

use wacht::api::organizations;
use wacht::models::CreateOrganizationRequest;

let org = organizations::create_organization(
    CreateOrganizationRequest::new("Acme Corp".to_string())
)
.send()
.await?;

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

​
With Optional Fields

use wacht::api::organizations;
use wacht::models::CreateOrganizationRequest;

let request = CreateOrganizationRequest {
    name: "Acme Corp".to_string(),
    description: Some("A sample organization".to_string()),
    public_metadata: Some(serde_json::json!({
        "industry": "Technology",
        "website": "https://acme.com"
    })),
    private_metadata: Some(serde_json::json!({
        "internal_notes": "Priority customer"
    })),
    organization_image: None,
};

let org = organizations::create_organization(request)
    .send()
    .await?;

​
Required Fields

  • name (String) - Organization name

​
Optional Fields

  • description (Option<String>) - Organization description
  • public_metadata (Option<serde_json::Value>) - Public metadata
  • private_metadata (Option<serde_json::Value>) - Private metadata
  • organization_image (Option<Vec<u8>>) - Organization image data

​
Update Organization

Update an existing organization’s information. Only provided fields will be updated. 
use wacht::api::organizations;
use wacht::models::UpdateOrganizationRequest;

let updated = organizations::update_organization(
    "org_123",
    UpdateOrganizationRequest {
        name: Some("Acme Corporation".to_string()),
        description: Some("Updated description".to_string()),
        public_metadata: Some(serde_json::json!({"updated": true})),
        ..Default::default()
    }
)
.send()
.await?;

​
Available Update Fields

All fields are optional - only include what you want to change:
  • name (Option<String>)
  • description (Option<String>)
  • public_metadata (Option<serde_json::Value>)
  • private_metadata (Option<serde_json::Value>)
  • disabled (Option<bool>)

​
Delete Organization

Permanently delete an organization. This action cannot be undone. 
use wacht::api::organizations;

organizations::delete_organization("org_123")
    .send()
    .await?;

​
Manage Organization Members

​
List Members

use wacht::api::organizations::members;

let members = members::list_members("org_123")
    .limit(50)
    .send()
    .await?;

for member in members.data {
    println!("{} - {} {}", member.role.name, member.user.first_name, member.user.last_name);
}

​
Add Member

use wacht::api::organizations::members;
use wacht::models::AddOrganizationMemberRequest;

// First get available roles to find the role ID
let roles = organizations::roles::list_roles("org_123")
    .send()
    .await?;

let member = members::add_member(
    "org_123",
    AddOrganizationMemberRequest {
        user_id: "user_456".to_string(),
        role_ids: vec![roles.data[0].id.clone()],
    }
)
.send()
.await?;

println!("Added member: {}", member.user.first_name);

​
Update Member Role

use wacht::api::organizations::members;
use wacht::models::UpdateMemberRoleRequest;

let updated = members::update_member_role(
    "org_123",
    "member_789",
    UpdateMemberRoleRequest {
        role_ids: vec!["new_role_id".to_string()],
    }
)
.send()
.await?;

​
Remove Member

use wacht::api::organizations::members;

members::remove_member("org_123", "member_789")
    .send()
    .await?;

​
Manage Organization Roles

​
List Roles

use wacht::api::organizations::roles;

let roles = roles::list_roles("org_123")
    .send()
    .await?;

for role in roles.data {
    println!("{} ({} permissions)", role.name, role.permissions.len());
}

​
Create Role

use wacht::api::organizations::roles;
use wacht::models::CreateRoleRequest;

let role = roles::create_role(
    "org_123",
    CreateRoleRequest {
        name: "Editor".to_string(),
        description: Some("Can edit content".to_string()),
        permissions: vec![
            "org:read".to_string(),
            "org:write".to_string(),
        ],
    }
)
.send()
.await?;

println!("Created role: {}", role.name);

​
Update Role

use wacht::api::organizations::roles;
use wacht::models::UpdateRoleRequest;

let updated = roles::update_role(
    "org_123",
    "role_456",
    UpdateRoleRequest {
        name: Some("Senior Editor".to_string()),
        description: Some("Advanced editing permissions".to_string()),
        permissions: Some(vec![
            "org:read".to_string(),
            "org:write".to_string(),
            "org:delete".to_string(),
        ]),
    }
)
.send()
.await?;

​
Delete Role

use wacht::api::organizations::roles;

roles::delete_role("org_123", "role_456")
    .send()
    .await?;

​
Error Handling

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

match organizations::fetch_organization_details("invalid_id").send().await {
    Ok(details) => println!("Organization: {}", details.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);
    }
}