Safeguard for Privileged Passwords (SPP) is built with an API-first design and uses a modernized API based on a REST architecture which allows other applications and systems to interact with it. Every function is exposed through the API to enable quick and easy integration regardless of what action you perform or in which language your applications are written. There are even a few things that can only be performed via the Safeguard SPP API.

CAUTION: Starting with SPP 6.8, any user that built a custom solution that monitors for events using ASP.NET SignalR will need to make changes to their solutions due to the upgrade to ASP.NET Core SignalR. For more information on this change and how to upgrade between the two versions, see the Microsoft documentation. Users that built custom solutions that do not rely on event monitoring via SignalR should not be impacted.

API tutorial

The SPP API tutorial is available on GitHub at: https://github.com/oneidentity/safeguard-api-tutorial.

Access the SPP API

SPP has the following API categories:

• Core: Most product functionality is found here. All cluster-wide operations: access request workflow, asset management, policy management, and so on.

  https://<Appliance IP>/service/core/swagger/

• Appliance: RAppliance-specific operations, such as setting IP address, maintenance, backups, support bundles, appliance management.

  https://<Appliance IP>/service/appliance/swagger/

• Notification: Anonymous, unauthenticated operations. This service is available even when the appliance isn't fully online.

  https://<Appliance IP>/service/notification/swagger/

• Event: Specialized endpoint for connecting to SignalR for real-time events.

  https<Appliance IP>event/signalr
  

• a2a: Application integration specific operations. Fetching passwords and SSH keys, making access requests on behalf of users, and so on.

  https://<Appliance IP>/service/a2a/swagger

You must use a bearer token to access most resources in the API. When using the Swagger web UI (as referenced in the URLs above), click the Authorize button at the top of each page and log in using the web UI. The Swagger web UI adds the bearer token to each API request automatically. However, if you are manually making the API request or writing your own application/script, perform the following two steps to obtain a bearer token.

1. You must first authenticate using the OAuth 2.0 Resource Owner Password Credentials or Client Credentials grant types.

   An example of Resource Owner Password Credentials is:

   POST https://<ApplianceIP>/RSTS/oauth2/token

   Host: <ApplianceIP>

   Content-Type: application/json

   Accept: application/json

    

   {

   "grant_type": "password",

   "username": "<Username>",

   "password": "<Password>",

   "scope": "rsts:sts:primaryproviderid:local"

   }

   Where:

   • grant_type is required and must be set to password.
   • username is required and set to the user account you want to log in as.
   • password is required and set to the password associated with the username.

   • scope is required and set to one of the available identity provider's scope ID. The value shown in the example request, rsts:sts:primaryproviderid:local, is the default value available on all SPP Appliances. User accounts that you create in SPP directly (that is, not an Active Directory or LDAP account) will most likely have this scope value.

     NOTE: The list of identity providers is dynamic and their associated scope ID can only be obtained by making a request to:

     https://<ApplianceIP>/service/core/v4/AuthenticationProviders

     and parsing the returned JSON for the RstsProviderScope property.

     NOTE: Certain OAuth 2.0 grant types can be disabled if they are not needed. For more information, see Local Login Control.

   If you wish to authenticate using a client certificate, you must use the OAuth 2.0 Client Credentials grant type in which your certificate is included as part of the SSL connection handshake and the Authorization HTTP header is ignored. Set the scope to rsts:sts:primaryproviderid:certificate or any other identity provider that supports client certificate authentication.

   POST https://<ApplianceIP>/RSTS/oauth2/token

   Host: <ApplianceIP>

   Content-Type: application/json

   Accept: application/json

    

   {

   "grant_type": "client_credentials",

   "scope": "rsts:sts:primaryproviderid:certificate"

   }

2. After successfully authenticating, your response will contain an access_token that must be exchanged for a user token to access the API.

   POST https://<ApplianceIP>/service/core/v4/Token/LoginResponse

   Host: <ApplianceIP>

   Content-Type: application/json

   Accept: application/json

    

   {

   "StsAccessToken": "<access_token from previous response>"

   }

You should now have an authorization token to be used for all future API requests. The token is to be included in the HTTP Authorization header as a Bearer token like this:

For example: