REST API Reference Download

Overview

The Secret Server REST API guides are version specific. In fact, they are automatically generated when a Secret Server version is created. Thus, to ensure you have the correct guides for your Secret Server version, it is best (but not required) to access the documentation from that version of Secret Server; however there are many reasons why this might not be practical, so we provide download links below.

Accessing the Guides

To access the guides:

  1. For Secret Server click the question mark icon in the top right of the dashboard and click REST API Guide. The Secret Server REST API Guide page appears.

  2. Accessing Secret Server through the API and scripts can be powerful mechanism but ensure you are following best practices with the account and access for any script connecting to Secret Server. The Secret Server Software Development Kit for DevOps is recommended for all automated or machine-to-machine scripts. If not using the SDK, creating an application account for the script access and limiting the permissions both from Role perspective and on Secret themselves is security best practice.

  3. On the Secret Server REST API page of your instance, choose one of the three guides:

    • Bearer token authentication: Hyperlinked documentation for REST API access using token authentication.
    • Token authentication: Instructions for getting an authentication token.
    • Windows Integrated Authentication: Hyperlinked documentation for REST API access using Integrated Windows Authentication (IWA).

Downloading the Guides

Only use the following links if you cannot easily access a guide from a version of Secret Server. There is a possibility the guides below are not the most current versions.

Current Version

Current Secret Server REST API Guide

Version Archive

Understanding API versioning

While you might still use some older endpoints, it is important to transition to the latest to take advantage of improved functionality and ongoing support. Our changes follow the OpenAPI standard, ensuring that updates do not disrupt your existing scripts by introducing new versions when necessary.

A transition to a new version is likely a part of an ongoing effort to improve the API's efficiency and functionality. We recognize that maintaining backward compatibility is crucial, and if at all possible we strive to maintain that compatibility, unless there is a compelling reason to not to.

  • Endpoint Changes: In a new version, some endpoints have equivalents to older ones, but they often differ significantly. For example, an endpoint with a new version might return different data, excluding some fields that were present in older versions. If any of the following changes happen, for any reason, we will publish a new version and leave the old one as is. While we try to avoid it, you may need to adjust your workflows to accommodate those changes.

    The possible changes are:

    • Changing the required input parameters (data type or a new requirement)
    • Changing the output data (data type or removing existing data)
    • Changing the data format of the input or output
We strongly recommend transitioning to new endpoints even if the old ones suffice. We cannot guarantee support for old endpoints.
  • Backward Compatibility Concerns: While the goal is to maintain backward compatibility, there are instances where significant improvements necessitate changes. While it is usual to introduce new endpoints instead of altering the old ones, it is not always possible.
  • Output Optimization: New endpoints are optimized to provide more relevant data, which might mean less information is returned. This can lead to a more efficient API, but you may need to adjust your workflows to accommodate these changes.
  • Field and Permission Adjustments: New versions may include changes in field configurations and permissions, affecting how you access and manipulate data. Even if the old outputs were extensive, the new version might require additional calls to retrieve specific field details.
  • New Functions: The new version may add functions and endpoints that do not have direct equivalents in the old version. Exploring these new features can enhance your use of the API.

Steps to Transition to New API Versions

  • Review Documentation: Make sure you have both the previous and the latest API documentation (above) to compare the old and new endpoints. This will help you understand the changes and how to implement them in your systems.
  • Identify Impacted Workflows: Determine which of your workflows rely on the old endpoints and assess how they will be affected by the transition to to the new ones. You may need to rework some processes to align with the new API structure.
  • Use the New Endpoints: Explore the new endpoints and functions in the updated version that can enhance your existing workflows or introduce new capabilities.