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::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 Organizations

Retrieve a paginated list of organizations from your deployment.

Basic List

// Fetch all organizations (default pagination)
let orgs = client.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

// Fetch organizations with builder options
let orgs = client.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 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.
let details = client.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::models::CreateOrganizationRequest;

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

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

With Optional Fields

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 = client.organizations().create_organization(request)
    .send()
    .await?;
request
CreateOrganizationRequest
required

Update Organization

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

let updated = client.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

request
UpdateOrganizationRequest
required

Delete Organization

Permanently delete an organization. This action cannot be undone.
client.organizations().delete_organization("org_123")
    .send()
    .await?;

Manage Organization Members

List Members

let members = client.organizations().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::models::AddOrganizationMemberRequest;

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

let member = client.organizations().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::models::UpdateMemberRoleRequest;

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

Remove Member

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

Manage Organization Roles

List Roles

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

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

Create Role

use wacht::models::CreateRoleRequest;

let role = client.organizations().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::models::UpdateRoleRequest;

let updated = client.organizations().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

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

Error Handling

All SDK methods return a Result<T, Error>:
use wacht::Error;

match client.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);
    }
}