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. > ℹ️ > > Some environments may still use an old-style API key, which is a formatted Globally Unique Identifier (GUID). Rotating the API Key produces the new-style API key described above. ### Session state 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. ### 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. ``` = 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. ``` = 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 (optional; required only if the **User Password** is required on the application API registration). ``` Authorization=PS-Auth key=c479a66f…c9484d; runas=doe-main\johndoe; pwd=[un1qu3]; ``` > ℹ️ > > 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. ### 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. > ℹ️ > > 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 When **Client certificate required** is enabled on API authentication, the following items are required to authenticate via API: - Client certificate must be present on the calling machine/instance. - Client certificate must be trusted by the appliance/Instance. - Client certificate must be included in script when calling Password Safe API. For cloud certificate authentication, the client certificate must be signed by a well-known CA for cloud instance to trust it and allow authentication. > ℹ️ > > The client cert can be downloaded from the Password Safe appliance/Instance in the Configuration > System > Downloads menu.

For examples of utilizing a client cert in your API script, refer to the default scripts in the resource kit for your relevant version.

### 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. When using a request body, if no version is specified in the URI, the default listed version is used (typically v3.0). To use a specific version, the version must be included in the URI. > ✅ **Example** > > https\://server/BeyondTrust/api/public/v3.1/endpoint ### Common response codes Below are response codes common to all APIs. Custom responses are detailed in the individual endpoints. - 200 – Request successful. - 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 and an email is sent to the administrator detailing the reason. Look here first for the reason why authorization failed. - 403: – Access forbidden. User does not have the appropriate role or permission. > ℹ️ > > A 403 can also occur when SSL trust cannot be established. - 404 – Object not found where expected. Reason in response body. - 500 – Unexpected server error occurred. #### Examples > ✅ **Example** 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("/Auth/SignAppin", content).Result; > ``` > >

Subsequent calls:

> > ``` > HttpResponseMessage getResponse = client.GetAsync("/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];"); > ``` > ✅ **Example** 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 = "/Auth/SignAppin"; > $signinResult = Invoke-RestMethod -Uri $uri -Method POST -Headers $headers -SessionVariable script:session; > ``` > >

Subsequent calls:

> > ``` > $uri = "/ManagedAccounts"; > $accounts = Invoke-RestMethod -Uri $uri -Method GET -WebSession $script:session -Headers $headers; > ``` > ✅ **Example** 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.setRequestProperty("Authorization","PS-Auth key=c479a66f…c9484d; runas=doe-main\\johndoe;"); > ``` > ✅ **Example** Ruby > >

Using the rest-client gem, carry over the ASP.NET_SessionId header.

> > ``` > samp_key = 'PS-Auth key= c479a66f…c9484d; runas=doe-main\\johndoe;' > result = RestClient::Request.execute(method: :post, url: '/Auth/SignAppin', :headers => {‘Authorization’ => samp_key} ) > session_id = result.cookies["ASP.NET_SessionId"] > ``` > >

Subsequent calls:

> > ``` > result = RestClient::Request.execute(method: :get, url: '/ManagedAccounts', :headers=>{‘Authorization’ => samp_key, :cookies => {'ASP.NET_SessionId' => session_id}} ) > ``` > ✅ **Example** 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('/Auth/SignAppin') > ``` > >

Subsequent calls:

> > ``` > accounts = session.get('/ManagedAccounts') > ``` > ✅ **Example** 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 https:/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 https:/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 /Auth/SignAppin** - **POST /Workgroups/{ID}/Assets** - **POST /Assets/{assetId}/ManagedSystems** - **POST /ManagedSystems/{managedSystemId}/ManagedAccounts** - **POST /QuickRules** - **POST /UserGroups** - **POST /UserGroups/{userGroupId}/SmartRules/{smartRuleId}/Roles** - **POST /Auth/Signout** ##### Retrieve a password Case: request, retrieve, and check in a password for a managed account: - **POST /Auth/SignAppin** - **GET /ManagedAccounts** OR **GET /ManagedAccounts?systemName={systemName}&accountName={accountName}** - **POST /Requests** - **GET /Credentials/{requestId}** - **PUT /Requests/{requestId}/Checkin** - **POST /Auth/Signout** ##### Create a session Case: request a session, create a session, and check in the request for a managed account: - **POST /Auth/SignAppin** - **GET /ManagedAccounts** OR **GET /ManagedAccounts?systemName={systemName}&accountName={accountName}** - **POST /Requests (AccessType="RDP" or AccessType="SSH" or AccessType="App")** - **POST /Requests/{requestId}/Sessions (SessionType == Request.AccessType above)** - **PUT /Requests/{requestId}/Checkin** - **POST /Auth/Signout** ##### Retrieve a password as an ISA Case: create an ISA password request: - **POST /Auth/SignAppin** - **GET /ManagedAccounts** OR **GET /ManagedAccounts?systemName={systemName}&accountName={accountName}** - **POST /ISARequests** - **POST /Auth/Signout** ##### Create a session as an ISA Case: create an ISA session: - **POST /Auth/SignAppin** - **GET /ManagedAccounts** OR **GET /ManagedAccounts?systemName={systemName}&accountName={accountName}** - **POST /ISASessions** - **POST /Auth/Signout** ## Authentication ### POST Auth/SignAppin #### Purpose Authenticates the provided credentials and creates a user session. #### Required permissions A user group to which the user belongs must be granted access to the API key given in authorization header. Must be running script from a valid source address as configured in API registration for the given API key. #### Request body None. #### Response body Content-Type: application/json ``` { UserId: int, SID: string, EmailAddress: string, UserName: string, Name: string } ``` #### Response codes - 200 – Request successful. User model in the response body. - 403 – Access forbidden. Returned if the Password Safe license is not valid. - 410 – API version has been disabled. ### POST Auth/Signout #### Purpose Terminates the current user session. #### Required permissions None. #### Request body None. #### Response body None. #### Response codes - 200 – Request successful. ### OAuth public API authentication ### POST Auth/Connect/Token #### Purpose Authenticates the provided credentials and allows access to the public API. #### Required permissions Application user must be associated to an API Access Policy API registration and must belong to a user group with necessary permissions. #### Request body Content-Type: application/x-www-form-urlencoded ``` grant_type=client_credentials&client_id=[user-client-id]&client_secret=[user-client-secret] ``` #### Response body Content-Type: application/x-www-form-urlencoded ``` { access_token: string, expires_in: int, token_type:string = “Bearer”, scope: string } ``` #### Response body details - **access\_token**: The privileged credential to use in the Authorization header for API requests to authenticate the use. - **expires\_in**: Lifetime (in seconds) that the token is valid. - **token\_type**: Describes the access token (always **Bearer**). - **scope**: Describes the scope of the access token, which is what the token is allowed to perform. For application users, this consists of only a scope called **publicapi**. ### POST Auth/SignAppIn #### Request body None . #### Header **Authorization**: Bearer \[access\_token\] > ℹ️ > > Cookies are still supported using this sign-in method.