REST APIs

This section includes CyberArk's REST API commands, how to use them, and samples for typical implementations.

Overview

Use REST APIs to create, list, modify and delete entities in PAM - Self-Hosted from within programs and scripts.

You can automate tasks that are usually performed manually using the UI, and to incorporate them into system and account-provisioning scripts.

REST APIs are part of the PVWA installation, and can be used immediately without any additional configuration. Make sure your CyberArk license enables you to use the CyberArk PAM - Self-Hosted SDK. For more information, contact your CyberArk support representative.

Our REST APIs are stable and predictable. If a change is needed in one of our APIs that causes the API to break, we will either create an alternate API or communicate the change in advance. Changes that break APIs are rare.

Changes that are considered to break an API:

  • Changing the URL
  • Changing a parameter name
  • Adding mandatory parameters
  • Removing parameters

Changes that are not considered to break an API:

  • Adding optional parameters in the request
  • Returning additional values in the response
  • Changes due to security issues
 

As a general rule, we recommend that you always use the newest REST API version. The newer versions include better performance and have more capabilities. If you cannot find a corresponding REST API for the task that you want to perform, you can use the command line interface (PACLI). For details, see Command Line Interface (PACLI) SDK.

Authorization requirement

For every REST API call except for Logon, the request must include an HTTPS header field named Authorization, containing the value of a session token received from the Logon activity.

For details about authentication, see Authentication.

SDK Supported Platforms

The PAM - Self-Hosted SDK is a RESTful API that can be invoked by any RESTful client for various programming and scripting environments, including Java, C#, Perl, PHP, Python and Ruby.

The PAM - Self-Hosted SDK

The PAM - Self-Hosted SDK enables you to perform activities on PAM - Self-Hosted objects via a REST Web Service interface. Each PAM - Self-Hosted object has its own URL path in the PVWA that can be accessed using the relevant HTTPS request verb.

Every HTTPS request must contain an HTTPS header field named Authorization that contains the value of a session token received from the Logon method.

REST APIs can be accessed with any tool or language that enables you to create HTTPS requests and handle HTTPS responses. For more information, refer to the C# and Java examples in Usage examples.

Swagger support

Try out our API commands in swagger (/PasswordVault/swagger).

In this section:

Return Codes

The following table lists all the return codes that are returned from the REST APIs.

Return Code

Code Number

Description

Success

200

The request succeeded. The actual response will depend on the request method used.

Created

201

The request was fulfilled and resulted in a new resource being created.

No Content

204

The server successfully processed the request and is not returning any content (no response body). This code is typically returned by DELETE requests.

Bad request

400

The request could not be understood by the server due to incorrect syntax.

Unauthorized

401

The request requires user authentication.

Forbidden

403

The server received and understood the request, but will not fulfill it. Authorization will not help and the request MUST NOT be repeated.

Not Found

404

The server did not find anything that matches the Request-URI. No indication is given of whether the condition is temporary or permanent.

Conflict

409

The request could not be completed due to a conflict with the current state of the resource.

Too Many Requests

429

The user has sent too many requests in a given amount of time ("rate limiting").

Internal Server Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request.

Not Implemented

501

The server does not support this operation due to version incompatibility.

Troubleshooting

This section includes information on troubleshooting issues.

405 Method not allowed

A delete request was sent to the Vault, and the following response was received:

405 Method not allowed.

Solution:

Uninstall WebDAV on the IIS.

REST API does not work

By default, HTTPS is configured. If REST APIs do not work, make sure that the binding is defined in the web.config file.

Solution:

  1. In the PasswordVault installation folder, open the web.config file.

  2. In the service tag, add bindingConfiguration="httpsBinding", as shown in the following example:

     

    <service behaviorConfiguration="defaultBehavior" name="CyberArk.WSAuthentication.Cyberark.CyberArkAuthenticationService">
    <endpoint name="AuthEndpoint" address="/" behaviorConfiguration="web" binding="webHttpBinding" bindingConfiguration="httpsBinding" contract="CyberArk.WSAuthentication.Cyberark.ICyberArkAuthenticationService" />
    </service>
    <service behaviorConfiguration="defaultBehavior" name="CyberArk.PasswordVault.WebServices.WF.PIMServices">
    <endpoint name="PIMEndpoint" address="/" behaviorConfiguration="web" binding="webHttpBinding" bindingConfiguration="httpsBinding" contract="CyberArk.PasswordVault.WebServices.WF.IPIMServices" />
    </service>

  3. Save the web.config file and close it.