Stop hand-sorting your PasswordSafe estate: lifecycle management with attributes, Smart Rules, and the API

Outline

• Why this comes up
• The idea in one paragraph
• Why an attribute and not something else
• A starting vocabulary
• Why decommission needs two states
• Building it
• Things that will bite you
• Pre-staging, which is the fun part
• An import connector is not a substitute for this
• Additional Resources

Why this comes up

I’m often having the same conversation when I show users the Dashboards → PasswordSafe and the failed password changes. A server gets decommissioned somewhere upstream, or a directory account is decommissioned, but nothing tells PasswordSafe of this change; often it’s an object that no longer matches the Smart Rule query for onboarding. Then I come along asking someone to investigate their password test failure report trying to work out whether a box is broken, gone, or was never finished being built in the first place. Multiply that by a few thousand systems, and managed accounts, and then the rotation failure report stops being a signal and starts being wallpaper. 🫠

Most PasswordSafe hygiene problems aren't PasswordSafe problems. They're lifecycle problems that arrive in PasswordSafe with nowhere to go.

There's a way out of this and it doesn't need a new product. It needs lifecycle state treated as data that lives on the object, and Smart Rules doing the sorting.

🚩 This is a general case. It assumes you have some automated lifecycle process to hook, and that you're comfortable with the PasswordSafe API. It doesn't cover Secrets Safe, Workforce Passwords, or Entra ID specifics, and it deliberately doesn't touch asset-level attributes — see Things that will bite you for why.

The idea in one paragraph

If your organisation has any automated lifecycle process, and most do, then you have an event you can hook. When a system changes state upstream, have that process call the PasswordSafe API and stamp a lifecycle attribute onto the matching managed system or managed account. Smart Rules read that attribute and sort the object into the right Smart Group, turn automatic management on or off, and keep it out of the groups where it doesn't belong. A separate Smart Rule catches everything under management with no lifecycle attribute at all, which becomes your exception queue.

Your upstream system stays the source of truth. PasswordSafe stays the enforcement point. The attribute is the contract between them.

This design deliberately lives at the managed system and managed account layer rather than the asset layer. Assets carry attributes too, but asset data is subject to discovery-driven retention behaviour that can clear attributes on a cycle, and the population you actually care about for credential hygiene is the population under management. One layer, one retention story, no ambiguity about which copy of the attribute is authoritative.

Why an attribute and not something else

Attributes are the only field on a PasswordSafe object where you control the vocabulary, Smart Rules can filter on it, and the API can write to it. Descriptions are free text and nobody agrees on the format. Workgroups are for password change agent routing. Smart Group membership is derived, not set. The attribute is the one place you can put a fact and have the rest of the platform act on it.

Attributes sit under Attribute Types, which act as the parent category. That structure matters more than it looks. Create an Attribute Type called something like Lifecycle State, hang your values underneath it, and you get a clean way to express "this object is in exactly one of these states." Scatter the values across unrelated types and you lose that.

A starting vocabulary

If your organisation already has lifecycle states defined, use those. Mirroring the vocabulary your teams already speak is worth more than a tidier set of words. If you're starting from nothing, this set is a reasonable base:

in-deployment — the system is in PasswordSafe but not finished. Credentials may be staged, but nothing should auto-rotate yet. This is the state that stops half-built systems generating rotation failures and training your team to ignore the report.

online — the system is expected to be up and under management. Keep environment out of this one. Production, development, and test belong in a separate Attribute Type, because a system can be a test box and online at the same time, and one attribute can't carry both facts.

archived — the system has stopped responding for longer than your chosen threshold, or has been flagged by the lifecycle process. This is deliberately not a decommission. An archived system might be a genuine outage, a disaster recovery site that's legitimately dark, or a decommission that was started upstream and never finished. Archiving gets it out of the failure reports without asserting it's gone.

decommissioned — the lifecycle process has marked it retired. Auto-management off, out of the active groups.

decommissioned-to-delete — the separate, deliberate second state. This is the one that matters most.

Best Practices are set by each organization and may have different requirements, so please follow your Best Practices as outlined by the change control policies of your organization. What follows is a Preferable Practices guide.

Why decommission needs two states

The gap between decommissioned and decommissioned-to-delete exists so mistakes are recoverable. Decommissioning is the state people get wrong, and a single-state model gives you no window to catch it. With two states, a system sits in decommissioned for whatever period your process defines, and rolling it back is a change of attribute. Nothing has been destroyed.

decommissioned-to-delete is the point of no return, and it earns the caution.

Two things to be clear about.

1. PasswordSafe won't delete assets, managed systems, or managed accounts for you. It can unlink them and mark them unmanaged, but deletion is a deliberate act. You can drive it programmatically, but every dependency has to be unwound first and the order matters. Managed accounts need to be deleted or unlinked before the decommissioned managed system can go.

2. More importantly: when the object goes, its logs go with it. Session records, password change history, and the audit trail for that object are part of what gets removed. Check your data retention obligations before you build anything that deletes on a schedule. This is the step most likely to be discovered after the fact, and it cannot be undone. Please.

Building it

Create the Attribute Type and its values. Configuration in the console, or POST AttributeTypes/{attributeTypeID}/Attributes in the BeyondInsight API. Short name and long name cap at 64 characters, description at 255. Requires Attribute Management (Read/Write).

Wire the lifecycle event to the API. Assigning an attribute is POST ManagedSystems/{managedSystemID}/Attributes/{attributeID} for managed systems and POST ManagedAccounts/{managedAccountID}/Attributes/{attributeID} for managed accounts. Each has a matching DELETE. Permissions needed are Attribute Management (Read/Write) plus PasswordSafe System Management or Account Management for whichever object you're writing to. Give the automation account those and nothing else.

The DELETE is not optional. Attributes are additive. Posting decommissioned onto an object already carrying online gives you an object carrying both, and your Smart Rules will now match it in two places. Every state transition in your automation should be a delete of the old value followed by a post of the new one. Skip this and the design fails quietly rather than loudly, which is worse.

Build the Smart Rules one at a time, preview first. These are Managed System and Managed Account rules, not asset-based ones. Create each rule with only the Show as Smart Group action, confirm the membership is what you expect, and only then add the actions that change things. The documentation recommends this and it's good advice, because a Smart Rule with a management action attached will act on whatever it matched, correctly or not.

Order your selection criteria so the filter that eliminates the most objects sits at the top. Filters are processed hierarchically.

Build the exception rule. One Smart Rule matching managed systems and accounts with no lifecycle attribute. This is your safety net and it's the rule that tells you whether the whole thing is working. Give it an owner and an email alert. An exception queue nobody reads is just a slower version of the problem you started with.

If the API isn't returning the anticipated data, or if the documentation is followed with challenging results? Yes, contact support. Want help structuring your code? No, that is outside the scope of support.

Things that will bite you

"Remove it from the other Smart Groups" is not an action. Smart Group membership is derived from criteria, not managed as a list. You don't remove an object from a group, you write the criteria so it no longer matches. In practice each lifecycle Smart Rule needs to exclude the other states explicitly, not just include its own. Getting the DELETE right on the API side is what makes this reliable.

Two Smart Rules, same objects, different actions, endless loop. This one is documented and it's the failure mode most likely to catch this design specifically, because attribute-based rules overlap easily. Make your lifecycle rules mutually exclusive by construction.

Onboarding is still asset-driven, and that seam is real. A managed system can't carry a lifecycle attribute before it exists as a managed system. So the attribute scheme governs everything already under management, and something else still has to get objects there: a discovery scan, an asset-based Smart Rule with the Manage Assets Using Password Safe action, or pre-staging by API. Decide which you're using and write it down, because "it should have been onboarded" is a different failure from "it was onboarded and mis-sorted," and only the second one shows up in your exception queue.

Smart Rules aren't instant. Reprocessing frequency is configurable and a lifecycle change lands at the next processing cycle, not at the moment the API call succeeds. Set expectations accordingly, especially if a change control process is waiting on it.

Nothing writes back. If somebody changes an attribute directly in PasswordSafe, your upstream system won't know. Decide up front whether PasswordSafe is allowed to be authoritative for anything, and if the answer is no, treat manual attribute edits as an incident rather than a shortcut.

Pre-staging, which is the fun part

Once this is running you can turn it around. Create the managed system in PasswordSafe by API before the box is finished, stamp it in-deployment, and leave it. Nothing rotates, nothing fails, nothing generates noise. Build and provisioning completes, the lifecycle process flips the attribute to online, and the Smart Rules pick it up and switch it into active management on their own. No ticket, no manual onboarding step, no gap between "server is live" and "server is under credential management."

Pre-staging is also what closes the onboarding seam above. If you create the managed object up front, the attribute is doing the work from the first moment the system exists, and there's no window where a live box sits outside the scheme waiting for a discovery scan to notice it. That window is where a lot of risk lives, and closing it costs you one API call in a process you already run.

An import connector is not a substitute for this

If you already have something pulling systems in from a CMDB, that's useful, but it solves a different problem. The current import mechanisms are pulling in IP information based on the target collection in the connector. The API route places this directly in the lifecycle path to, and provides the granularity that may not exist with how the connectors are configured. The benefit of the API-in-the-lifecycle path provides the reflexive model that survives beyond CMDB.

So the two are complementary rather than competing. Let whatever you have handle discovery and existence. Use the API to carry the state, because that's the part nothing else is carrying.

The wider point

None of this is specific to decommissioning. Attributes plus Smart Rules is a general-purpose sorting mechanism, and any fact your organisation already tracks about a system can become one. Compliance scope. Ownership. Patch window. Data classification. If a fact drives a different credential management decision, it can be an attribute, and the decision can be automatic.

Password check and rotation hygiene stops being a monthly cleanup exercise and starts being a property of the system.

Additional Resources

• Smart Rules in Password Safe: https://docs.beyondtrust.com/bips/docs/ps-smart-rules 
• Assets: Overview, including the onboarding paths into Password Safe: https://docs.beyondtrust.com/bips/docs/bi-assets 
• BeyondInsight API, Attributes: https://www.beyondtrust.com/docs/beyondinsight-password-safe/ps/api/beyond-insight/attributes.htm 
• Password Safe API, Attributes on managed systems and accounts: https://www.beyondtrust.com/docs/beyondinsight-password-safe/ps/api/password-safe/attributes.htm 
• KB0018994 and KB0019495 — Smart Group best practices, on the Customer Portal

Documentation checked against BeyondInsight and Password Safe v26.2. Verify behaviour against your own version before building.

Happy sorting!

Tasha