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 the Deprecation of V1

Version 1 (V1) of the Secret Server API has been deprecated and is no longer supported. While you might still be using some V1 endpoints, it's important to transition to V2 to take advantage of improved functionality and ongoing support. This change follows the OpenAPI standard, ensuring that updates do not disrupt your existing scripts by introducing new versions when necessary.

Key Differences You Should Know

  • Endpoint Changes: In V2, some endpoints have equivalents in V1, but they often differ significantly. For example, the /v1/secret-templates/{secrettemplateid} endpoint has a V2 version that returns different data, excluding some fields that were available in V1. It's important to note that while V2 aims to optimize output, it may require adjustments to workflows to accommodate these changes.

  • Backward Compatibility Concerns: While the goal is to maintain backward compatibility, there are instances where significant improvements necessitate changes. In hindsight, some endpoints might have been better introduced as entirely new endpoints rather than as part of V2, especially when they differ substantially from their V1 counterparts.

  • Output Optimization: V2 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: V2 may include changes in field configurations and permissions, affecting how you access and manipulate data. While V1 outputs were extensive, V2 might require additional calls to retrieve specific field details.

  • New Functionalities: V2 introduces new functionalities and endpoints that may not have direct equivalents in V1. Exploring these new features can enhance your use of the API.

Steps to Transition to V2

  • Review Documentation: Make sure you have the latest API documentation, which provides clear guidance on the differences between V1 and V2 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 V1 endpoints and assess how they will be affected by the transition to V2. You may need to rework certain processes to align with the new API structure.

  • Utilize New Endpoints: Explore the new endpoints and functionalities in V2 that can enhance your existing workflows or introduce new capabilities.

Note on API Versioning

The transition to V2 is part of an ongoing effort to improve the API's efficiency and functionality. However, it's acknowledged that maintaining backward compatibility is crucial, and future changes will strive to adhere to this principle unless there is a compelling reason to deviate.