11/6/22, 10:04 AM BeyondInsight / Password Safe - Getting started with Password Safe API - Step-by-Step Guide for Configuring,

ring, Testing and Trou…

Home  Knowledge  Knowledge Search  KB0017018

KB0017018 - Latest Version 

Getting started with Password Safe API -

Step-by-Step Guide for Configuring, Testing
and Troubleshooting
 Revised by Courtney Norman
•
 about a month ago •  198 Views •     

The purpose of this article is to give an understanding of the configuration and execution of API’s within
BeyondInsight/Password Safe. It will provide all the steps required to configure BeyondInsight/Password Safe
to accept an API script to return the password of an Active Directory managed account. In addition, there are
some troubleshooting steps and scripts attached for additional testing.

PRE-REQUISITE
Within your Active Directory environment, create an account to be used as a Managed Account:
Example BI Managed Account: ‘domain\managed’
(Please review KB0018178 for information on adding managed accounts).

CONFIGURING
1. Login to BeyondInsight as an administrator account.
2. Navigate to Configuration > General > API registrations:

https://beyondtrustcorp.service-now.com/csm?id=kb_article_view&sysparm_article=KB0017018&sys_kb_id=8f7d960c47469d101bf1db37536d439f&s… 1/11
11/6/22, 10:04 AM BeyondInsight / Password Safe - Getting started with Password Safe API - Step-by-Step Guide for Configuring, Testing and Trou…
3. Click on ‘Create API Registration’ and give it a name to identify it (in this case ‘API_Test’)

4. Click on the ‘add Authentication Rule’ to provide a list of the allowed IP addresses where the API
scripts will be run from. If using a proxy/forwarder/load balancer, make sure to allow those as well. If they
are not using forwarding rules, the source IP address will not match that of the requestor machine. In this
example we are allowing a large range of IP addresses to make sure this works:

5. Once the rule is updated – this will make the API connection ‘Active’. You can also include an
additional option such as ‘Client Certificate Required’ or ‘User password Required’ in this example – we
will leave these turned off.

https://beyondtrustcorp.service-now.com/csm?id=kb_article_view&sysparm_article=KB0017018&sys_kb_id=8f7d960c47469d101bf1db37536d439f&s… 2/11
11/6/22, 10:04 AM BeyondInsight / Password Safe - Getting started with Password Safe API - Step-by-Step Guide for Configuring, Testing and Trou…

6. Now go to Configuration > Role Based Access > User Management, we will add a new local group
called API Users. Then selecting the Users section Create a new local user APIUSER which will be used
as the account to run the API.

https://beyondtrustcorp.service-now.com/csm?id=kb_article_view&sysparm_article=KB0017018&sys_kb_id=8f7d960c47469d101bf1db37536d439f&s… 3/11
11/6/22, 10:04 AM BeyondInsight / Password Safe - Getting started with Password Safe API - Step-by-Step Guide for Configuring, Testing and Trou…
Then selecting the Users section Create a new local user APIUSER which will be used as the account
to run the API.

7. To keep this simple, this group has been given access to the ‘All Managed Accounts’ Smartrule and
the role is that of a requestor with auto-approval for access to Password Only. Now select the ‘Enable
Application API’ option at the bottom and select the API registration you created at the top of this guide.

https://beyondtrustcorp.service-now.com/csm?id=kb_article_view&sysparm_article=KB0017018&sys_kb_id=8f7d960c47469d101bf1db37536d439f&s… 4/11
11/6/22, 10:04 AM BeyondInsight / Password Safe - Getting started with Password Safe API - Step-by-Step Guide for Configuring, Testing and Trou…

8. We have added a ‘Managed Account’ called ‘Mana Ged’ which will be used by the API to retrieve its
password.

9. Select the account and click the ellipses and select Edit Managed Account. Scroll to the Account
Setting section and make sure the ‘Enable for API access’ slider is selected. Scroll to the bottom and

https://beyondtrustcorp.service-now.com/csm?id=kb_article_view&sysparm_article=KB0017018&sys_kb_id=8f7d960c47469d101bf1db37536d439f&s… 5/11
11/6/22, 10:04 AM BeyondInsight / Password Safe - Getting started with Password Safe API - Step-by-Step Guide for Configuring, Testing and Trou…
select Update Account.

10. Now link the managed account to an asset onboarded into BeyondInsight. In Managed Systems,
select the system and click the ellipses then "Go to Advanced Details". Click on "Linked Accounts" and
make sure the show filter is set to All or Not Linked. Select the Managed Account and click the Link
Accounts button.

TESTING
Your system is now configured and ready for a script to be run to return the password for <Managed Account>
by <Group> against asset <Hostname>. In order to do this, we shall use the script provided below – The
following variables will need to be modified to fit in with your environment/settings:

$baseUrl : Make sure this is pointing to the appliance (IP address)

$apiKey : Copy the API key from here:

https://beyondtrustcorp.service-now.com/csm?id=kb_article_view&sysparm_article=KB0017018&sys_kb_id=8f7d960c47469d101bf1db37536d439f&s… 6/11
11/6/22, 10:04 AM BeyondInsight / Password Safe - Getting started with Password Safe API - Step-by-Step Guide for Configuring, Testing and Trou…

$runAsUser : The BI WebConsole User inside the group with API Access enabled (in this example, this is
APIUSER).
$systemName : The target system to which the Managed Account is linked (in this example, this is BI-PWS-
Test).
$accountName : The managed account name.
Copy the embedded script at the end of the document onto the server you have allowed and open it in an
elevated ‘Windows PowerShell ISE’ window.
Now paste the Test API script into the white area and ensure all editable fields match your environment, and
press the green Arrow (highlighted below).

If your script is successfully run – you will see something like this:

https://beyondtrustcorp.service-now.com/csm?id=kb_article_view&sysparm_article=KB0017018&sys_kb_id=8f7d960c47469d101bf1db37536d439f&s… 7/11
11/6/22, 10:04 AM BeyondInsight / Password Safe - Getting started with Password Safe API - Step-by-Step Guide for Configuring, Testing and Trou…

TROUBLESHOOTING
If you have 401 errors when running the script, this normally points to one or more of the following:
- User does not have API Access
- User has API Access but access to this specific API has not been enabled
- IP address is not allowed for that API
- Sometimes toggling the API registration checkmark for the API USERS group make help

If you pass the authentication, you might see some 404 errors. This does not mean that there are issues with
the requested web resource but that the requested account was not found:
- Check that the Managed Account is enabled for API
- Check that the Managed Account is linked to that target system
- Sometimes the Frontend log or PublicAPI log (7.0 and above) may show Managed Account not found, even if
the managed account is Onboarded to Password Safe, and has been enabled for API. Previous SmartRules
used to Onboard the Managed Account may revert it back to not being API enabled when they run.

https://beyondtrustcorp.service-now.com/csm?id=kb_article_view&sysparm_article=KB0017018&sys_kb_id=8f7d960c47469d101bf1db37536d439f&s… 8/11
11/6/22, 10:04 AM BeyondInsight / Password Safe - Getting started with Password Safe API - Step-by-Step Guide for Configuring, Testing and Trou…
In the smart rule Actions section, find the Account options section and ensure that the Enable API Access is
selected if applicable to the Users included in the Smart Rule

NOTE: PLEASE ALSO REFER TO OUR OFFICIAL API DOCUMENTATION HERE

KB0017019 can be referenced for information on how to implement X-Forwarded-For rules when utilizing a load
balancer.

Test API Script

Please see below an example of a script for API tests

Additional Information:
https://beyondtrustcorp.service-now.com/csm?id=kb_article_view&sysparm_article=KB0017018&sys_kb_id=8f7d960c47469d101bf1db37536d439f&s… 9/11
11/6/22, 10:04 AM BeyondInsight / Password Safe - Getting started with Password Safe API - Step-by-Step Guide for Configuring, Testing and Trou…
See also attached example API Powershell scripts:

Test API

Retrieve Password

Creating Multiple Managed Accounts (from CSV)

Create RDP Session File

Refresh/Sync Group Members

Add User Group Permissions

Export Team Passwords (to CSV files)

NOTE: MORE SAMPLE SCRIPTS ARE PROVIDED IN THE PASSWORD SAFE RESOURCE KIT
AVAILABLE IN THE DOWNLOADS PORTAL. THE SAMPLE SCRIPTS PROVIDED HERE ARE FOR
TESTING ONLY, IT IS RECOMMENDED TO REVIEW THEIR CONTENT AND UNDERSTAND THE
COMMANDS PRIOR TO RUNNING IN YOUR ENVIRONMENT. IF ADMINISTRATORS WOULD LIKE
ASSISTANCE WITH CREATING A SPECIFIC API PROCESS FOR THEIR ENVIRONMENT, PLEASE
REACH OUT TO YOUR ACCOUNT MANAGER TO DISCUSS OPTIONS WITH PROFESSIONAL
SERVICES.

Copy Permalink

Was this article helpful? Yes No

Rate this article     

Also in Configuration & Best Practices

Password Safe Functional Account Creation Guide

 499 Views

How to apply the all updates package provided by support

 257 Views

How to download and install PS Automate

 191 Views

BeyondTrust Remote Execution Service

 174 Views

How do I migrate from the BeyondTrust Network Security Scanner to the BeyondTrust Discovery Agent?
 162 Views

View all 117 articles

https://beyondtrustcorp.service-now.com/csm?id=kb_article_view&sysparm_article=KB0017018&sys_kb_id=8f7d960c47469d101bf1db37536d439f&… 10/11
11/6/22, 10:04 AM BeyondInsight / Password Safe - Getting started with Password Safe API - Step-by-Step Guide for Configuring, Testing and Trou…

Most Viewed for BeyondInsight / Password Safe

Password Safe Functional Account Creation Guide

 499 Views

Upgrade BeyondInsight/Password Safe in an Active/Passive Appliance setup

 311 Views

How to confirm basic connectivity and pre-requisites required by Password Safe for Active Directory Connections
 298 Views

How to configure Application Sessions in Password Safe

 284 Views

How to apply the all updates package provided by support

 257 Views

Top Rated for BeyondInsight / Password Safe

Remote Desktop can't find the computer


How to collect debug logs for PasswordSafe and BeyondInsight.

RDP fails with Failed to connect RDP session error - Extend timeout in registry

Troubleshooting Services, Scheduled Tasks and IIS App Pools used with Managed Accounts

How to configure Application Sessions in Password Safe


https://beyondtrustcorp.service-now.com/csm?id=kb_article_view&sysparm_article=KB0017018&sys_kb_id=8f7d960c47469d101bf1db37536d439f&… 11/11