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:

  
https://api.alero.io/v2/<command>

For example:

  
https://api.alero.io/v2/sites

Use the following URL:

  
https://api.alero.io/v2-edge/<command>

For example:

  
https://api.alero.io/v2-edge/sites

 

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

  • The request requires user authentication.

  • Your session has expired and your user has been disconnected

Forbidden

403

  • The request was valid, but the server is refusing action. The user might not have the necessary permissions for the action.

  • The request was valid, but the usage limit according to the license was reached.

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.