Hudu Passwords

Hudu Passwords Management

Overview

Passwords in Hudu (called "asset passwords" in the API) provide secure credential storage scoped to companies. They allow MSP technicians to store, organize, and retrieve credentials for client infrastructure, applications, and services. Password access can be restricted at the API key level, and all access is logged in Hudu's activity logs.

Critical API naming note: The Hudu UI calls these "Passwords," but the API endpoint is /api/v1/asset_passwords. Always use asset_passwords in API calls.

Key Concepts

Password Organization

Passwords are organized by:

• Company - Each password belongs to a specific company
• Password Folders - Hierarchical folder structure within a company
• Name - Descriptive name identifying the credential

Company: Acme Corporation
+-- Passwords
    +-- Infrastructure
    |   +-- Domain Admin - ACME
    |   +-- Local Admin - Servers
    |   +-- vCenter Admin
    +-- Network
    |   +-- Firewall Admin
    |   +-- Switch Admin
    |   +-- WiFi Controller
    +-- Applications
    |   +-- ERP Admin
    |   +-- CRM Admin
    +-- Cloud Services
        +-- Microsoft 365 Global Admin
        +-- AWS Root Account

API Key Password Permission

API keys in Hudu can be configured to allow or deny password access:

Permission	Effect
Enabled	API key can read/write password values
Disabled	API key cannot access password values (403 Forbidden)

This is configured per API key in Admin > API Keys.

Security Audit Trail

Hudu logs all password access in the activity logs (/api/v1/activity_logs). This includes:

• Who accessed the password
• When it was accessed
• What action was performed (view, create, update, delete)

Field Reference

Core Fields

Field	Type	Required	Description
id	integer	System	Auto-generated unique identifier
company_id	integer	Yes	Parent company
name	string	Yes	Password display name
username	string	No	Account username
password	string	No	The actual password value
url	string	No	Related URL/login page
description	string	No	Additional notes
password_type	string	No	Category/type label
otp_secret	string	No	TOTP/2FA secret

Password Folder Fields

Field	Type	Description
password_folder_id	integer	Folder location
password_folder_name	string	Folder name (read-only)

Metadata Fields

Field	Type	Description
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp
slug	string	URL-friendly identifier
url	string	Full URL in Hudu
object_type	string	Always "AssetPassword"

API Patterns

List Passwords

GET /api/v1/asset_passwords
x-api-key: YOUR_API_KEY
Content-Type: application/json

By Company:

GET /api/v1/asset_passwords?company_id=123

By Name:

GET /api/v1/asset_passwords?name=Domain Admin

With Pagination:

GET /api/v1/asset_passwords?company_id=123&page=1

Combined:

GET /api/v1/asset_passwords?company_id=123&name=admin

Get Single Password

GET /api/v1/asset_passwords/789
x-api-key: YOUR_API_KEY

Response:

{
  "asset_password": {
    "id": 789,
    "company_id": 123,
    "company_name": "Acme Corporation",
    "name": "Domain Admin - ACME",
    "username": "administrator@acme.local",
    "password": "SecureP@ssw0rd123!",
    "url": "https://dc01.acme.local",
    "description": "Primary domain administrator account.\nUse for:\n- Domain controller management\n- Group Policy changes\n- AD user management",
    "password_type": "Administrative",
    "password_folder_id": 45,
    "password_folder_name": "Infrastructure",
    "otp_secret": null,
    "slug": "domain-admin-acme",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2025-11-15T14:22:00.000Z",
    "url": "https://your-company.huducloud.com/passwords/789"
  }
}

IMPORTANT: The password value is returned in the response. Never expose password values in correlation summaries, logs, or output visible to unauthorized users.

Create Password

POST /api/v1/asset_passwords
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "asset_password": {
    "company_id": 123,
    "name": "Domain Admin - ACME",
    "username": "administrator@acme.local",
    "password": "SecureP@ssw0rd123!",
    "url": "https://dc01.acme.local",
    "description": "Primary domain administrator account",
    "password_type": "Administrative",
    "password_folder_id": 45
  }
}

Update Password

PUT /api/v1/asset_passwords/789
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "asset_password": {
    "password": "NewSecureP@ssw0rd456!",
    "description": "Password rotated on 2026-02-15. Previous rotation: 2025-11-15."
  }
}

Delete Password

DELETE /api/v1/asset_passwords/789
x-api-key: YOUR_API_KEY

Warning: Consider keeping passwords for audit purposes. Deletion requires DELETE permission on the API key.

Search Passwords

By Name:

GET /api/v1/asset_passwords?name=Domain Admin

By Company:

GET /api/v1/asset_passwords?company_id=123

Combined:

GET /api/v1/asset_passwords?company_id=123&name=firewall

Common Workflows

Secure Password Creation

async function createSecurePassword(companyId, data) {
  const password = await createAssetPassword({
    company_id: companyId,
    name: data.name,
    username: data.username,
    password: data.password,
    url: data.url,
    description: `Created: ${new Date().toLocaleDateString()}\nPurpose: ${data.purpose}`,
    password_type: data.type,
    password_folder_id: data.folderId
  });

  return password;
}

Password Rotation Workflow

async function rotatePassword(passwordId, newPassword, reason) {
  // Get current password info (for logging, not the value)
  const current = await getAssetPassword(passwordId);

  // Update with new password
  const updated = await updateAssetPassword(passwordId, {
    password: newPassword,
    description: `${current.description || ''}\nRotated: ${new Date().toLocaleDateString()} - ${reason}`
  });

  return updated;
}

Password Search by Context

async function findPasswordsForServer(companyId, serverName) {
  const passwords = await fetchAssetPasswords({ company_id: companyId });

  return passwords.filter(p =>
    p.name.toLowerCase().includes(serverName.toLowerCase()) ||
    p.description?.toLowerCase().includes(serverName.toLowerCase()) ||
    p.url?.toLowerCase().includes(serverName.toLowerCase())
  );
}

Find Stale Passwords

async function findStalePasswords(companyId, daysOld = 90) {
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - daysOld);

  const passwords = await fetchAssetPasswords({ company_id: companyId });

  return passwords
    .filter(p => new Date(p.updated_at) < cutoffDate)
    .map(p => ({
      id: p.id,
      name: p.name,
      username: p.username,
      lastUpdated: p.updated_at,
      daysSinceUpdate: Math.floor(
        (new Date() - new Date(p.updated_at)) / (1000 * 60 * 60 * 24)
      )
    }));
}

Password Inventory Report

async function generatePasswordReport(companyId) {
  const passwords = await fetchAssetPasswords({ company_id: companyId });

  const byType = {};
  passwords.forEach(p => {
    const type = p.password_type || 'Uncategorized';
    if (!byType[type]) byType[type] = [];
    byType[type].push({
      name: p.name,
      username: p.username,
      url: p.url,
      lastUpdated: p.updated_at
      // NEVER include actual password values in reports
    });
  });

  return byType;
}

Security Best Practices

Access Control

1. Restrict API key permissions - Only enable password access on keys that need it
2. Use company-scoped keys - Limit API keys to specific companies when possible
3. IP whitelist - Restrict API key usage to known IPs
4. Regular access reviews - Audit who has API keys with password access

Password Hygiene

1. Regular rotation - Rotate passwords on schedule (90 days recommended)
2. Strong passwords - Enforce complexity requirements
3. Unique passwords - Never reuse passwords across systems
4. Track changes - Update description when passwords are rotated
5. Monitor stale passwords - Alert on passwords not updated recently

Output Safety

CRITICAL: Never include actual password values in:

• Correlation summaries or reports
• Log files
• Chat output or conversation history
• Error messages
• Any output that may be visible to unauthorized users

When displaying password information, always mask the actual value:

Password: Domain Admin - ACME
Username: administrator@acme.local
Password: **************
URL:      https://dc01.acme.local

Audit Logging

Monitor password access using Hudu's activity logs:

GET /api/v1/activity_logs?resource_type=AssetPassword&resource_id=789

Error Handling

Common API Errors

Code	Message	Resolution
400	Name can't be blank	Provide password name
400	Company is required	Include company_id
401	Invalid API key	Check HUDU_API_KEY
403	Password access denied	API key lacks password permission
404	Password not found	Verify password ID
422	Validation failed	Check required fields

Validation Errors

Error	Cause	Fix
Name required	Missing name	Add name to request
Company required	No company_id	Include company_id
Access denied	API key lacks permission	Enable password access on API key
Invalid folder	Bad folder_id	Query password folders first

Secure Error Handling

async function safeGetPassword(passwordId) {
  try {
    return await getAssetPassword(passwordId);
  } catch (error) {
    if (error.status === 403) {
      console.log('Password access denied. API key may lack password permission.');
      return null;
    }

    if (error.status === 404) {
      console.log('Password not found.');
      return null;
    }

    throw error;
  }
}

Best Practices

1. Use descriptive names - Include system name and account type (e.g., "Domain Admin - ACME")
2. Set password type - Classify passwords (Administrative, Network, Application, etc.)
3. Organize with folders - Create a logical folder hierarchy per company
4. Document purpose - Use the description field to explain what the password is for
5. Track URLs - Always include the login URL when applicable
6. Regular rotation - Establish password rotation schedules
7. Monitor access - Review activity logs for password access
8. Avoid deletion - Archive or keep passwords for audit trails
9. Include 2FA - Store TOTP secrets with the otp_secret field
10. Never expose values - Never include password values in summaries or logs

Related Skills

• Hudu Companies - Password company scope
• Hudu Assets - Device-related credentials
• Hudu Articles - Embedding passwords in articles
• Hudu Websites - Website credentials
• Hudu API Patterns - API reference