Automate with APIs
This topic explains how developers can use the SWS APIs to automate tasks that are usually performed manually in the SWS portal.
Overview
The SWS APIs enable you to perform activities on SWS resources via a REST Web Service interface. Each SWS resource has its own URL path that can be accessed using the relevant HTTPS request verb.
SWS service account
A SWS service account enables you to use the SWS API to authenticate to SWS and access data. For information about how to create them, and how to use them to call SWS APIs, see Using service accounts.
API versions
SWS offers two types of APIs:
Version |
Description |
---|---|
Stable |
A set of REST APIs released by CyberArk with official documentation, support, SDK, and more. |
Edge |
A newer version of REST APIs released by CyberArk. This is a POC version and these APIs are subject to change. Currently we have v1 and v2 of Edge. v2 is updated with latest features. |
You can manually change the version of the selected API by specifying the version to implement in the URL, as shown in the following examples:
Use the following URL:
|
For example:
|
Use the following URL:
|
For example:
|
|
Make sure the command specifies the correct data center. To call a SWS API from the US data center, make sure the suffix in the URL is .io. For example, api.alero.io. To call a SWS API from the EU data center, make sure the suffix in the URL is .eu. For example, api.alero.eu. To call a SWS API from the Canada data center, make sure the URL is correct. For example, api.ca.alero.io. To call a SWS API from the Australia data center, make sure the URL is correct. For example, api.au.alero.io. |
Return codes
The following table lists all the return codes that are returned from the REST Web Services API.
Return Code |
Code Number |
Description |
---|---|---|
Success |
200 |
The request succeeded. The actual response depends on the request method used. In a GET request, the response contains an entity corresponding to the requested resource. In a POST request, the response contains an entity describing or containing the result of the action. |
Created |
201 |
The request was fulfilled and resulted in a new resource being created. |
Accepted |
202 |
The request has been accepted for processing, but the processing has not been completed. |
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 |
|
Forbidden |
403 |
|
Not Found |
404 |
The requested resource could not be found, or the user does not have permissions for this resource. |
Method Not Allowed |
405 |
A request method is not supported for the requested resource. |
Request Timeout |
408 |
The request was received by the server, but there was a timeout reaching one of the next components. Try again later. |
Conflict |
409 |
The request could not be completed due to a conflict with the current state of the resource. |
Internal Server Error |
500 |
The server encountered an unexpected condition which prevented it from fulfilling the request. |