API registration | PS Cloud

What are APIs?

Application Programming Interfaces (APIa), act as a bridge that lets programs communicate with each other securely and efficiently.

How is API registration useful?

API registrations allow you to integrate part of the BeyondInsight and Password Safe functionality into your applications, which allows you to expand your application's overall functionality and provide enhanced security and access management.

Administrators can configure two types of API registrations in BeyondInsight:

One method uses an API key.
The second method uses an Open Authorization (OAuth) authentication access policy for application users. Setting up each type of registration is detailed in the sections below.

Add an API key policy API registration

To create an API key policy API registration:

Use a browser to sign in to your BeyondInsight/Password Safe URL.
This URL is provided in the BeyondTrust welcome email and includes your site URL followed by /login.
From the left menu, click .
The Configuration page displays.
Under General, select API Registrations.
The API Registrations page displays.
Click Create API Registration.
Select API Key Policy from the dropdown.
The Details pane displays.
Fill out the new API registration details:
- Select the Authentication Rule Options you wish to enable:
  - Enforce multi-factor authentication: This setting is enabled by default. When enabled, requires users to abide by multi-factor authentication settings configured for Password Safe. Disabling this setting bypasses multi-factor authentication when accessing user accounts through API. This allows applications integrated with Password Safe using an API key to abide by multi-factor authentication settings configured for the application, as opposed to using the Password Safe settings.
  - Client Certificate Required: When enabled, a client certificate is required with the web request, and if not enabled, client certificates are ignored and do not need to be present. A valid client certificate is any client certificate that is signed by a Certificate Authority trusted by the server on which BeyondInsight resides.
  - User Password Required: When enabled, an additional Authorization header value containing the RunAs user password is required with the web request. If not enabled, this header value does not need to be present and is ignored if provided.
    
    Square brackets surround the password in the header. For example, the Authorization header might look like:
```
Authorization=PS-Auth key=c479a66f…c9484d; runas=doe-main\johndoe; pwd=[un1qu3];
```
  - Verify PSRUN Signature: The PSRUN signature is an extra level of authentication. It’s computed from the factors using a shared secret between the client and server. PSRUN sends the signature as part of the header during its API request. If enabled, the server recomputes the signature during factor validation and compares it against the one sent by the client. If the signatures match, the client’s identity is considered verified. The signature effectively keeps the client in sync with the server. Changing the secret on the server requires the client to be rebuilt and guarantees that out-of-date clients cannot authenticate.
- An authentication rule must be included. Click Add Authentication Rule.
  - At least one IP rule or PSRUN rule is required, providing a valid source IP address (IPv4 or IPv6), an IP range, or CIDR from which requests can be sent for this API key (one IP address, IP range, or CIDR per line).
  - X-Forwarded-For rules can also be created, providing a valid source IP address (IPv4 or IPv6), an IP range, or CIDR from which requests can be sent for this API key. In a load-balanced scenario, IP authentication rules are used to validate the load balancer IPs, and the X-Forwarded-For header is used to validate the originating client IP. Existing rules cannot be changed from an IP rule to a X-Forwarded-For rule, or vice versa.
  - If an X-Forwarded-For rule is configured, it is required on the HTTP request (only a single header is allowed on the request). If the X-Forwarded-For header is missing, the request fails with a 401 Unauthorized error.
  - Click Create Rule.
Click Create Registration.

BeyondInsight generates a unique identifier (API key) that the calling application provides in the Authorization header of the web request. The API key is masked and can be shown in plain text by clicking the Show Key icon next to the Key field. The API key can also be manually rotated, or changed, by clicking the circular arrow.

ℹ️
Once the key has been changed, any script using the old key receives a "401 Unauthorized" error until the new key is used in its place. Read access and rotation of the key is audited.

Add Application User API access policy

Application Users are service accounts that represent any non-human identity that needs access to secrets and credentials. Typical use cases include:

Automated workflows - Providing credentials or secrets for custom workflows, and automating the administrative activities for managing data within the solution.
DevOps CI/CD - Leverage native integrations for DevOps tools like Ansible, Terraform, and Kubernetes.
Solutions integration - Enable other security or IT tools to integrate and leverage protected privileged credentials or secrets for securing external automation.
Agentic AI - Integrate directly with MCP servers to enable access to other datastores and provide rich context to your agents while maintaining security best practices and compliance mandates.

These Application Users are limited to interacting with the public API and authenticate using the OAuth client credential flow. When creating an application user you must provide an API registration of the type API Access Policy, which is specifically used for application users.

OAuth is an open standard protocol that allows users to grant limited access to their resources on one website or application to another website or application without sharing their credentials, such as username or password. By enhancing Password Safe authentication to support OAuth, Password Safe application users can benefit from improved overall security and the ease of integration that this feature provides.

OAuth uses access tokens, which are short-lived secrets that grant access to specific resources or APIs on behalf of the application user. Users can revoke access to Password Safe for any connected application or service. This provides more robust control over access to sensitive information.

Configure API Access Policy registration

The API Access Policy registration is used specifically for OAuth.

To create this in the BeyondInsight console:

Use a browser to sign in to your BeyondInsight/Password Safe URL.
This URL is provided in the BeyondTrust welcome email and includes your site URL followed by /login.
From the left menu, click .
The Configuration page displays.
Under General, select API Registrations.
The API Registrations page displays.
Click Create API Registration.
Select API Key Policy from the dropdown.
The Details pane displays.
Fill out the new API registration details, including the Access Token Duration. This field determines how long the OAuth token stays active.
Click Add Authentication Rule and enter the required information.
Click Create Rule.
Click Create Registration.

Add an application user

Application users represent applications that interface with the BeyondInsight public API. Application users cannot sign in to the BeyondInsight console. They can only authenticate and interact with the public API, using Client ID and Client Secret for credentials within the OAuth client credential flow.

An API Registration type of an API Access Policy must be assigned to an application user and is used for processing IP rules. To create an application user:

Use a browser to sign in to your BeyondInsight/Password Safe URL.
This URL is provided in the BeyondTrust welcome email and includes your site URL followed by /login.
From the left menu, click .
The Configuration page displays.
Under Role Based Access, select User Management.
The User Management page displays.
Click the Users tab.
Click Create New User above the grid.
Select Add an Application User from the dropdown.
The Create New Application User panel displays.
Add a username.
Under API Access Policy, select the policy.
Copy and save the information from the Client ID and Client Secret fields for later use.
Click Create User.
Assign the user to a group that has the required permissions to access BeyondInsight and Password Safe features.
- Locate the user in the grid.
- Click > View User Details.
- From the User Details pane, click Groups.
- Locate and select the group in the grid.
- Click Assign Group above the grid.

Recycle the client secret for an application user

When you edit an application user, you have an option to recycle their secret. Once recycled, you can copy or view the new secret. When a secret is recycled and the user account is updated with this change, the previous client secret is no longer valid.

To recycle the secret for an application user:

Use a browser to sign in to your BeyondInsight/Password Safe URL.
This URL is provided in the BeyondTrust welcome email and includes your site URL followed by /login.
From the left menu, click .
The Configuration page displays.
Under Role Based Access, select User Management.
The User Management page displays.
Click the Users tab.
Locate the user in the grid.
Click > Edit User Details.
Click to the right of the Client Secret to recycle it.
Click Recycle on the confirmation message that displays.
Copy and save the new secret for later use.
Click Update User.

View and update OAuth secret expiry

The user's secret eventually expires. The Users grid has an OAuth Secret Expiry column, which you can use to view what is close to expiring. The default duration of a client secret is 365 days. You can adjust the lifetime of the secret from the Authentication Options configuration area in BeyondInsight. Updating this value only changes the secret expiry date for new application users and recycled client secrets. Older secrets cannot be updated.

To view the OAuth Secret Expiry for an application user:

Use a browser to sign in to your BeyondInsight/Password Safe URL.
This URL is provided in the BeyondTrust welcome email and includes your site URL followed by /login.
From the left menu, click .
The Configuration page displays.
Under Role Based Access, select User Management.
The User Management page displays.
Click the Users tab.
Locate the application user. The OAuth Secret Expiry column lists the date and time that a client secret for that user expires.

To update the duration for client secrets:

Use a browser to sign in to your BeyondInsight/Password Safe URL.
This URL is provided in the BeyondTrust welcome email and includes your site URL followed by /login.
From the left menu, click .
The Configuration page displays.
Under Authentication Management, select Authentication Options.
The Authentication Options page displays.
Under Application User Authentication Settings, enter the new duration of the client secret in the Client Secret Expiry field.
Click Save.