Technical Tip: Using the Reveal platform APIs

The Reveal platform provides a series of REST APIs for querying data and managing users and nodes. 

Connecting to the API:

Users can use any tool to interact with the Reveal REST APIs. Examples include Postman, Python Requests, PowerShell's Invoke-RestMethod, or with curl commands directly. This guide is not intended to be an explainer on any specific tool, so should be read in conjunction with documentation for the chosen API tooling.

Authentication:

Authentication to the API is done using Bearer Authentication. This requires including an access token along with every request to the API. Operators can generate new access tokens using the Admin -> Access Tokens page.

Note that a role must be specified at generation time, which will restrict which permissions the token has access to. Fortinet recommends using a least-privilege model for all API Tokens, whereby a dedicated role is created with the fewest permissions needed to complete the required function(s).

Once generated, the Token will be displayed only once. It should be treated as with any other password and stored securely in a token or password manager. If used as part of scripts, Fortinet recommends storing it as an environment variable and referencing this variable in the scripts, rather than saving a copy of the token directly in any script(s).

Tokens are automatically generated with a 30-day expiry. To create a longer-lasting token, this must be done using the Admin -> Directory page:

Note: 

It is not possible to generate, modify, or delete access tokens via the API. This must now be done through the Reveal UI.

Content Types:

All supported requests to and responses from the Reveal API are in JSON format, with content-type application/json. Uploading of binary files for policy groups and assets is not currently supported via the API.

API Explorer:

The Reveal platform provides details of all available APIs as part of a dynamically generated API explorer. This API reference is available to operators after signing in and looking on the Admin -> About page:

Commands can be tried out directly via the API explorer. With each being color-coded to match the HTTP method needing to be used (blue for GET, green for POST, etc.).

If any part of the request URL contains curly braces ( e.g. {uuid} ) this means that section must be replaced with a variable, such as an agent unique ID:

Some commands may take a JSON formatted request body in addition to URL parameters, for example, in this case, the 'filter' section has been modified to search for all users with names starting with 'John':

The API explorer is pre-authenticated with permissions matching the current operator's role. As such, any example Curl commands will not include an access token header. This token should be included if running outside of the API explorer.

For example:

The curl command to run this locally would be:

curl -X GET 'https://reveal-support-us.reveal.nextdlp.com/api/v1/admin/version' -H 'accept: application/json' -H "Authorization: Bearer $token"  

Where '$token' is an environment variable corresponding to an access Token.