---
updatedAt: 2026-03-26T14:57:03.000Z
---

# API registration | PS Pathfinder

## What are APIs?

Application Programming Interfaces (APIs), 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.

> ℹ️
>
> Currently, Pathfinder requires that public API calls be made directly to the Password Safe Cloud load balancer. Users calling the Password Safe Public API should use the Base API Endpoint:
>
> <https://pf71226d.ps-dev.beyondtrustcloud.com/BeyondTrust/api/public/v3>

## Add an API key policy API registration

To create an API key policy API registration:

1. At the top left of the page, click ![Main menu icon](https://files.readme.io/8008765b74ecfb3975c6ad5d13f4705ec95477331afdfe9472f38b917fc0baf3-menu.png) **> Password Safe > Configuration**.\
   The **Configuration** page displays.

2. Under **General**, select **API Registrations**.

3. Click **Create API Registration**.

4. Select **API Key Policy** from the dropdown list.\
   The **Details** pane displays.

[block:image]{"images":[{"image":["https://files.readme.io/26802140017a6acc8feda41e1d118bb4eb602039eabc1e37a7dbb39a9baa05af-add_api_key_pathfinder.png",null,"API Registrations page"],"align":"center"}]}[/block]

5. Fill out the new API registration details:

   * Select the **Authentication Rule Options** you wish to enable:

     * **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  Password Safe vresides.
     * **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**.
6. Click **Create Registration**.

Password Safe 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:

1. At the top left of the page, click ![Main menu icon](https://files.readme.io/8008765b74ecfb3975c6ad5d13f4705ec95477331afdfe9472f38b917fc0baf3-menu.png) **> Password Safe > Configuration**.\
   The **Configuration** page displays.
2. Under **General**, select **API Registrations**.
3. Click **Create API Registration**.
4. Select **API Access Policy** from the dropdown list.\
   The **Details** screen is displayed.
5. Fill out the new API registration details, including the **Access Token Duration**. This field determines how long the OAuth token stays active.
6. Click **Add Authentication Rule**, enter the required information, and then click **Create Rule**.

### Add an application user

Application users represent applications that interface with the public API. Application users cannot log in to the user portal. 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 API Access Policy must be assigned to an application user, and is used for processing IP rules. To create an application user:

1. At the top left of the page, click ![Main menu icon](https://files.readme.io/8008765b74ecfb3975c6ad5d13f4705ec95477331afdfe9472f38b917fc0baf3-menu.png) **> Password Safe > Configuration**.\
   The **Configuration** page displays.
2. Under **Role Based Access**, click **User Management**.
3. Click the **Users** tab to display the list of users in the grid.
4. Click **Create New User** above the grid.
5. Select **Add an Application User** from the dropdown.\
   The **Create New Application User** screen displays.
6. Add a username.  
7. Under **API Access Policy**, select the policy.
8. Copy the information from the **Client ID** and **Client Secret** fields for later use.
9. Click **Create User**.
10. Assign the user to a group that has the required permissions to access Password Safe features.
    * Click the vertical ellipsis for the user, and then select **View User Details**.
    * From the **User Details** pane, click **Groups**.
    * Locate the group, select it, and click **Assign Group** above the grid.

#### Recycle the client secret for an application user

When editing 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:

1. At the top left of the page, click ![Main menu icon](https://files.readme.io/8008765b74ecfb3975c6ad5d13f4705ec95477331afdfe9472f38b917fc0baf3-menu.png) **> Password Safe > Configuration**.\
   The **Configuration** page displays.
2. Under **Role Based Access**, click **User Management**.
3. Click the **Users** tab.
4. Locate the application user in the grid.
5. Click the ellipsis to the right of the user, and then select **Edit User Details**.
6. Click ![Refresh icon](https://files.readme.io/b56514444903be6c6cd10e0d91f4b29f754a810b946275f18c5905c3e84f6a28-refresh.png) to the right of the **Client Secret**.
7. Click **Recycle** on the confirmation message.
8. Copy the new secret for later use.
9. Click **Update User**.

#### View and update OAuth secret expiry

The user's secret will eventually expire. 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. 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:

1. At the top left of the page, click ![Main menu icon](https://files.readme.io/8008765b74ecfb3975c6ad5d13f4705ec95477331afdfe9472f38b917fc0baf3-menu.png) **> Password Safe > Configuration**.\
   The **Configuration** page displays.
2. Under **Role Based Access**, click **User Management**.
3. Click the **Users** tab.
4. 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:

1. At the top left of the page, click ![Main menu icon](https://files.readme.io/8008765b74ecfb3975c6ad5d13f4705ec95477331afdfe9472f38b917fc0baf3-menu.png) **> Password Safe > Configuration**.\
   The **Configuration** page displays.
2. Under **Authentication Management** click **Authentication Options**.
3. Under **Application User Authentication Settings**, enter the new duration of the client secret in the **Client Secret Expiry** field.
4. Click **Update Application User Authentications Settings**.