Automate with APIs

The Remote Access APIs enable you to automate tasks that are usually performed manually in the Remote Access console.

Using the Remote Access APIs

The Remote Access APIs enable you to perform activities on Remote Access resources via a REST Web Service interface. Each Remote Access resource has its own URL path that can be accessed using the relevant HTTPS request verb.

For information about the codes returned by the Remote Access API commands, refer to Return codes.

Service Accounts

A Remote Access Service Account enables you to use the Remote Access API to authenticate to Remote Access and access data. For information about service accounts, how to create them, and how to use them to call Remote Access APIs, see Service accounts.

API versioning

Remote Access offers two sets of APIs:

Version

Description

Stable

A set of REST APIs released by CyberArk with official documentation, support, SDK, etc.

Edge

A newer version of REST APIs released by CyberArk. This is a POC version and these APIs are subject to change.

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.

 

Make sure the command specifies the correct data center.

To call an Remote Access API from the US data center, make sure the suffix in the URL is .io. For example, api.alero.io.

To call an Remote Access API from the EU data center, make sure the suffix in the URL is .eu. For example, api.alero.eu.

To call an Remote Access API from the Canada data center, make sure the URL is correct. For example, api.ca.alero.io.

To call an Remote Access API from the Australia data center, make sure the URL is correct. For example, api.au.alero.io.

To call an Remote Access API from the London data center, make sure the URL is correct. For example, api.uk.alero.io.

Use the following URL:

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

For example:

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

Use the following URL:

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

For example:

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

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 will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain 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.

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.