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
Number of results to return (max 100).
Number of results to skip.
Search query to filter results.
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
Organization description.
public_metadata
Option<serde_json::Value>
Public metadata.
private_metadata
Option<serde_json::Value>
Private metadata.
Organization logo or image byte data.
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
public_metadata
Option<serde_json::Value>
Public metadata to merge.
private_metadata
Option<serde_json::Value>
Private metadata to merge.
Set to true to disable the organization.
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 );
}
}