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.

Anti-triggers

• A credential needed to authenticate a tool call — Hudu passwords document the customer's credentials. They are never the connector's own auth: gateway credentials are brokered centrally and are not readable from anywhere in this plugin. An agent that reaches here to "find the API key" has taken a wrong turn.
• A credential stored on an asset rather than as a password record — many MSPs put licence keys and service accounts in asset custom fields. Those are not asset_passwords; use hudu-assets.
• The same credential in IT Glue — the other documentation platform in this marketplace stores passwords too, with its own permission model. Start from itglue-api-patterns.
• Resetting or rotating the credential on the actual system — this skill updates the documented value only. Changing the real password is a tenant or directory operation; use cipp-users or m365-users. Editing the record without changing the system leaves documentation that is confidently wrong.

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) — who accessed it, when, and what action (view, create, update, delete):

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

Fields

Core fields: company_id (required), name (required), username, password, url, description, password_type, otp_secret, password_folder_id.

See references/fields.md for the complete field reference.

API Patterns

Operation	Request
List / filter	GET /api/v1/asset_passwords?company_id=123&name=Domain Admin&page=1
Get one	GET /api/v1/asset_passwords/789
Create	POST /api/v1/asset_passwords with { "asset_password": { ... } }
Update	PUT /api/v1/asset_passwords/789
Delete	DELETE /api/v1/asset_passwords/789 (requires DELETE permission)

GET on a single password returns the plaintext password value in the response body. Treat every response from this endpoint as sensitive.

See references/api.md for the complete endpoint catalog with request/response examples.

Output Safety

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

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

Hudu keeps no rotation history of its own — append rotation dates to description so the audit trail survives.

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

The API filters only on name and company_id; matching against description or URL requires a client-side pass.

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;
}

Gotchas

• Endpoint is asset_passwords, not passwords. The UI name and the API name differ; /api/v1/passwords does not exist.
• 403 on this endpoint is a key-permission problem, not a bad key. Password access is a per-API-key toggle in Admin > API Keys — a key that works everywhere else can still 403 here.
• url appears twice in responses with different meanings: the credential's login URL on create/update, and the Hudu record URL in the read payload's metadata. Do not round-trip it blindly.
• Every read is logged. Bulk enumeration of passwords generates a visible audit trail; scope by company_id rather than sweeping the tenant.
• Deletion is unrecoverable and drops the audit context. Prefer keeping stale credentials with a rotation note.

See references/errors.md for the complete error and validation table plus a secure error-handling pattern.

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. Unique passwords - Never reuse passwords across systems
3. Track changes - Update description when passwords are rotated
4. Monitor stale passwords - Alert on passwords not updated recently

Documentation Hygiene

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. Include 2FA - Store TOTP secrets with the otp_secret field

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