DocumentationAPI ReferenceRelease Notes
API Reference

BeyondInsight and Password Safe API usage

This document specifies the Representational State Transfer (REST) compliant Application Programmer Interface (API) over HTTPS for BeyondInsight and Password Safe. It is a way to integrate a portion of the BeyondInsight and Password Safe functionality into your own applications.

Using the REST API makes it easier for users to build customized solutions for their specific needs while ensuring secure data transmission. The API provides a set of predefined operations, or endpoints, that can be accessed using HTTP Requests, including GET requests to retrieve data, POST requests to create new data, PUT requests to update existing data, and DELETE requests to remove data.

This resource is intended for readers with knowledge of HTTPS request and response processing, web development, and JSON notation.

Usage

API key

The API key is a cryptographically strong random sequence of numbers hashed into a 128-character string. It is encrypted and stored internally using AES 256 encryption. Any language with a Representational State Transfer (REST) compliant interface can access the API with the API key and RunAs in the authorization header.

Session state

This section describes API key authentication. Session state is maintained between API calls. The method is dependent on the scripting language. Initiate a session using API POST Auth/SignAppIn and always call POST Auth/Signout when you are done.

A successful sign-in returns a session cookie. Your HTTP client must store that cookie and send it on every subsequent request; the examples below show how to do this in each language. The session expires after 20 minutes of inactivity, after which you must sign in again.

If you authenticate with an OAuth bearer token instead, a session is optional. See OAuth public API authentication below.

The authentication endpoints are:

  • POST Auth/SignAppIn - authenticate and establish a session.
  • POST Auth/Signout - end the session.
  • POST Auth/Connect/Token - obtain an OAuth bearer token. See OAuth public API authentication below.

Base endpoint

The following base endpoint is used throughout this document. For on-premises instances, the-server is a placeholder and should be replaced with the server name in your environment.

{base} = https://the-server/BeyondTrust/api/public/v3

For cloud instances, the-cloud-instance-url is a placeholder and should be replaced with the cloud instance URL in your environment.

{base} = https://the-cloud-instance-url/BeyondTrust/api/public/v3

SSL is required to use the Password Safe Public API.

Authorization header

Use the web request authorization header to communicate the API application key, the RunAs username, and the user password:

  • key: The API key configured in BeyondInsight for your application.
  • runas: The username of a BeyondInsight user that has been granted permission to use the API key.
  • pwd: The RunAs user password surrounded by square brackets (required only if the User Password factor is enabled on the application API registration).
  • token: A Personal Access Token (required only if the Personal Access Token factor is enabled on the application API registration). See Authentication factors below.
  • challenge: The answer to a two-factor challenge. See Two-Factor authentication below.
Authorization=PS-Auth key=c479a66f…c9484d; runas=doe-main\johndoe; pwd=[un1qu3];

Parameter names are not case sensitive. Semicolons separate parameters, so a value may not contain one - except pwd, which is read as everything between its square brackets and so may contain semicolons.

⚠️

The pwd value must be enclosed in square brackets and followed by a semicolon. If either is omitted the password is read as empty and the request fails with 401. The token value requires neither.

ℹ️

The API keys in the examples have been shortened for brevity. A domain user is being used. When using a domain user, depending on the programming or scripting tool used, you may need to escape the backslash (\) character between the domain name and username.

Authentication factors

An API registration may require one or more additional factors beyond the API key. Each is configured on the registration in BeyondInsight:

  • Multi-factor authentication - see Two-Factor authentication below.
  • User password - supply the pwd parameter in the authorization header.
  • Personal Access Token - supply the token parameter in the authorization header.
  • Source address - the request must originate from an address allowed by the registration.
  • X-Forwarded-For - the request must carry an X-Forwarded-For header containing exactly one address.

When a required factor is missing or invalid the request fails with 401 and a generic message. The specific reason is not returned in the response; it is recorded in a BeyondInsight User Audit entry.

Repeated failures of the user password, Personal Access Token or two-factor factors count towards the account lockout threshold configured in BeyondInsight, and will lock the RunAs user once it is reached. An invalid API key does not count towards it. A successful sign-in resets the counter.

Personal Access Tokens

To authenticate with a Personal Access Token:

  1. Create the token for the user in the BeyondInsight console. There is no Public API endpoint for creating one.
  2. Enable the Personal Access Token factor on the API registration.
  3. Supply the token in the authorization header using the token parameter.
Authorization=PS-Auth key=c479a66f…c9484d; runas=doe-main\johndoe; token=8f14e45fceea167a;
ℹ️

An expired token and an invalid token produce the same response. Both count towards the account lockout threshold.

Two-Factor authentication

Depending on how the two-factor server is configured, a programmatic two-factor challenge is sometimes required.

No challenge

If the two-factor server is configured to authenticate through a push or mobile two-factor challenge, a challenge response is often not required. The first call to POST Auth/SignAppIn logs the user in, as long as the authentication request to the two-factor server does not time out.

Challenge

When a two-factor challenge is configured, two calls to POST Auth/SignAppIn are required and session state must be maintained between these two calls to validate the two-factor challenge.

The initial call to POST Auth/SignAppIn results in a 401 Unauthorized response which contains a header WWW-Authenticate-2FA containing the prompt from the authentication service. The prompt can be used to prompt the user for the challenge answer.

ℹ️

If the WWW-Authenticate-2FA header is not present, a two-factor authentication challenge has not been configured for the user.

When the challenge answer has been received from the user, POST Auth/SignAppIn is called again with the challenge answer in the authorization header, similar to the other authorization parameters:

  • challenge: The answer to the two-factor challenge.
Authorization=PS-Auth key=c479a66f…c9484d; runas=doe-main\johndoe; pwd=[un1qu3]; challenge=543687;
ℹ️

The challenge answer is only required on the second call to POST Auth/SignAppIn and not on subsequent requests.

OAuth public API authentication

The OAuth sign-in method uses the OAuth client credential flow. The client credentials grant type is used by clients to obtain an access token outside of the context of a user.

Only users with user type Application, who are associated to an API Access Policy API registration in BeyondInsight, can use this authentication method.

Obtain an access token from POST Auth/Connect/Token, then send it on subsequent requests:

Authorization: Bearer [access_token]

With a bearer token you can work in either of two ways.

  • Send the token on every request. You do not need to call POST Auth/SignAppIn at all. Each request is authenticated on its own and no session is created, so the sign-in and sign-out steps described under Session state and shown in the workflows below do not apply. This is the simpler option.
  • Call POST Auth/SignAppIn once with the token. This also creates a session cookie, so later requests can be made with the cookie alone, as they are with API key sign-in.
⚠️

Once the session exists it runs on its own 20-minute idle timeout and no longer depends on the token. Later cookie-only requests are not checked against the token's expiry, so the session keeps working after the token has expired, until the session itself times out. If you need access to stop when a token expires, send the token on every request instead of establishing a session.

ℹ️

Impersonation for the OAuth client credential flow is different than API key. Instead of providing the RunAs user as part of the Authorization header you provide the RunAs user using a new RunAs header. You can only impersonate users who are in the same group as the application user.

ℹ️

Setting up an OAuth authentication method requires the following steps:

  • Create an API Registration using the API Access Policy type
  • Create an application user
  • Assign your access policy to the user
  • Record their client ID and secret for later use
  • Assign user to a group with necessary permissions

Use certificates with APIs

⚠️

Client certificate authentication has been removed and is no longer supported for API registrations. An API registration that still has Client certificate required enabled will fail to authenticate. Update the registration to clear that setting.

Request body

For Password Safe API Endpoints, some request bodies have multiple versions available. The request body versions allow for different sets of data to be sent to a API endpoint dependent on what needs to be accomplished by the request. Each request body version is outlined on its relevant endpoint and these body versions are only relevant to their listed URI.

The version is supplied as a version query parameter. If it is omitted the default version is used, which is 3.0 unless the endpoint states otherwise. Only endpoints that document a version parameter support this.

https://the-server/BeyondTrust/api/public/v3/endpoint?version=3.1

Common response codes

Below are response codes common to all APIs. Custom responses are detailed in the individual endpoints.

  • 200 – Request successful.
  • 201 – Request successful. Resource created.
  • 204 – Request successful. No content in body.
  • 400 – Bad Request – Validation failure, missing request body, or string values exceed the maximum length. Reason in response body.
  • 401 – Unauthorized – User is not authenticated. Typical reasons include:
    • An invalid product license was detected.
    • The request headers were not set properly.
    • The server could not verify the validity of the request (due to one or more API factors).
    • The user session has expired.
    • The API key has been rotated but has not been updated in the calling script or application.
ℹ️

When you encounter a 401 error due to factor validation failure, a User Audit entry is created in BeyondInsight detailing the reason. Look here first for the reason why authorization failed.

  • 403: – Access forbidden. User does not have the appropriate role or permission.
  • 404 – Object not found where expected. Reason in response body.
  • 409 – Conflict. The request conflicts with the current state of the resource. Reason in response body.

Examples

Each example signs in, then reuses the session cookie on subsequent calls.

C#

Create and reuse a persistent connection using the System.Net.Http.HttpClient class.

HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization",
"PS-Auth key=c479a66f…c9484d; runas=doe-main\\johndoe;");

string json = Newtonsoft.Json.JsonConvert.SerializeObject(null);
System.Net.Http.StringContent content = new StringContent(json);
content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/json");

HttpResponseMessage signInResponse = client.PostAsync("{base}/Auth/SignAppIn", content).Result;

Subsequent calls:

HttpResponseMessage getResponse = client.GetAsync("{base}/ManagedAccounts").Result;

User Password factor enabled (header example only):

HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization",
"PS-Auth key=c479a66f…c9484d; runas=doe-main\\johndoe; pwd=[un1qu3];");
PowerShell

PowerShell internally creates a session variable to use for each subsequent call; Invoke-RestMethod CmdLet options -SessionVariable and -WebSession respectively. In the below example, the variable is named "session" and has script-level scope.

$headers = @{ Authorization="PS-Auth key=c479a66f…c9484d; runas=doe-main\johndoe;"; };
$uri = "{base}/Auth/SignAppIn";
$signinResult = Invoke-RestMethod -Uri $uri -Method POST -Headers $headers -SessionVariable script:session;

Subsequent calls:

$uri = "{base}/ManagedAccounts";
$accounts = Invoke-RestMethod -Uri $uri -Method GET -WebSession $script:session -Headers $headers;
Java

Create and reuse a persistent connection using the java.net.HttpURLConnection class.

URL baseURL = new URL("HTTPS", "the-server", 443, "/BeyondTrust/api/public/v3/");
URL url = new URL(baseURL, "Auth/SignAppIn");
HttpURLConnection conn = (HttpURLConnection)url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization","PS-Auth key=c479a66f…c9484d; runas=doe-main\\johndoe;");
Ruby

Using the rest-client gem, carry the cookies returned by sign-in over to subsequent requests.

samp_key = 'PS-Auth key=c479a66f…c9484d; runas=doe-main\\johndoe;'
result = RestClient::Request.execute(method: :post, url: '{base}/Auth/SignAppIn', :headers => {'Authorization' => samp_key} )
cookies = result.cookies

Subsequent calls:

result = RestClient::Request.execute(method: :get, url: '{base}/ManagedAccounts', headers: {'Authorization' => samp_key}, cookies: cookies)
Python

Create and reuse a persistent connection using the requests module.

header = {'Authorization': 'PS-Auth key=c479a66f…c9484d; runas=doe-main\\johndoe;'}
session = requests.Session()
session.headers.update(header)
response = session.post('{base}/Auth/SignAppIn')

Subsequent calls:

accounts = session.get('{base}/ManagedAccounts')
Bash

Using curl, option -c stores authentication information for subsequent requests and -b uses it in subsequent API calls.

curl -i -c apiToken -X POST {base}/Auth/SignAppIn -H "Content-Type: application/json" -H "Authorization: PS-Auth key=c479a66f…c9484d; runas=doe-main\\johndoe;" -d ""

Subsequent calls:

curl -i -b apiToken -X GET {base}/ManagedAccounts

Workflow

There are some loose dependencies between the APIs. A typical sequence is to list accounts or find an account, request a password, retrieve that password (once approved), and then release the password.

Create and manage an asset, create user group, assign roles

Case: Create and manage an asset, create a managed account, create a managed account quick rule, create/provision an LDAP/AD/BeyondInsight user group, grant Read access to new Smart Rule with requester role and access policy.

  • POST {base}/Auth/SignAppIn
  • POST {base}/Workgroups/{ID}/Assets
  • POST {base}/Assets/{assetId}/ManagedSystems
  • POST {base}/ManagedSystems/{managedSystemId}/ManagedAccounts
  • POST {base}/QuickRules
  • POST {base}/UserGroups
  • POST {base}/UserGroups/{userGroupId}/SmartRules/{smartRuleId}/Roles
  • POST {base}/Auth/Signout
Retrieve a password

Case: request, retrieve, and check in a password for a managed account:

  • POST {base}/Auth/SignAppIn
  • GET {base}/ManagedAccounts OR GET {base}/ManagedAccounts?systemName={systemName}&accountName={accountName}
  • POST {base}/Requests
  • GET {base}/Credentials/{requestId}
  • PUT {base}/Requests/{requestId}/Checkin
  • POST {base}/Auth/Signout
Create a session

Case: request a session, create a session, and check in the request for a managed account:

  • POST {base}/Auth/SignAppIn
  • GET {base}/ManagedAccounts OR GET {base}/ManagedAccounts?systemName={systemName}&accountName={accountName}
  • POST {base}/Requests (AccessType="RDP" or AccessType="SSH" or AccessType="App")
  • POST {base}/Requests/{requestId}/Sessions (SessionType == Request.AccessType above)
  • PUT {base}/Requests/{requestId}/Checkin
  • POST {base}/Auth/Signout
Retrieve a password as an ISA

Case: create an ISA password request:

  • POST {base}/Auth/SignAppIn
  • GET {base}/ManagedAccounts OR GET {base}/ManagedAccounts?systemName={systemName}&accountName={accountName}
  • POST {base}/ISARequests
  • POST {base}/Auth/Signout
Create a session as an ISA

Case: create an ISA session:

  • POST {base}/Auth/SignAppIn
  • GET {base}/ManagedAccounts OR GET {base}/ManagedAccounts?systemName={systemName}&accountName={accountName}
  • POST {base}/ISASessions
  • POST {base}/Auth/Signout

Updated 21 days ago

Updated 21 days ago

©2003-2026 BeyondTrust Corporation. All Rights Reserved. Other trademarks identified on this page are owned by their respective owners. BeyondTrust is not a chartered bank or trust company, or depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.