/passwords

name: "Hudu Passwords"
description: >
  Hudu secure credential storage: the /api/v1/asset_passwords endpoint
  (the UI calls these "Passwords"), company scoping and password
  folders, TOTP secrets, per-API-key password permissions, activity-log
  auditing, rotation workflows, and output-safety rules for handling
  plaintext credential values.
when_to_use: >-
  When storing, retrieving, rotating, or auditing credentials in Hudu, or when a request
  returns 403 on a password endpoint. Use when: hudu password, hudu credential, credential
  lookup, password management, secure credentials, hudu credentials, password storage,
  credential documentation, password access, or asset password.

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](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](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 C