REST API

Overview

The REST API enables connectivity with custom-built applications, public cloud services not natively supported by Entitle, and ETL processes for applications lacking REST API support—for example, those managing permissions through database queries.

The REST API can connect to non-public IP addresses for internal customer applications and services. For example, a Kubernetes (K8s) agent installed on a private cloud can connect to these applications.

ℹ️

Note

See the Entitle agent installation guide for more information.

Click here to view an example of how an implemented HTTP server for REST API integration should look.

This page will provide you with instructions on how to integrate Entitle and REST API.

General guidelines

• To integrate REST API with Entitle, you are required to implement an HTTP server that supports one of two integration modes: Standing Accounts or Ephemeral Accounts:
  1. Standing Accounts means only existing users will be given access.
  2. Ephemeral Accounts means temporary users are created and given access. After that, the users are deleted.
• Within the two integration modes, you can choose whether you wish to implement get all permissions (get_all_permissions) or get asset permissions (get_asset_permissions).

Set up REST API to work with Entitle

ℹ️

Note

In each of the two integration modes, there are mandatory and optional fields that can be implemented.

Standing Accounts:

1. Mandatory fields to implement:
   1. get_all_permissions or get_asset_permissions
   2. get_assets
   3. get_actors
   4. give_access
   5. revoke_access
2. Optional fields:
   1. check_config
   2. create_actor
   3. delete_actor

Ephemeral Accounts:

1. Mandatory fields to implement:
   1. get_all_permissions or get_asset_permissions
   2. get_assets
   3. create_actor
   4. delete_actor
2. Optional fields:
   1. check_config

Definitions of entities

Below you will find an explanation for each entity that exists as a field (mandatory and optional ones).

Actor

An actor represents an entity that interacts with assets within a system. This actor could be a user, a service account, or any entity that requires access to resources or performs actions within the system.

Asset

An asset represents a resource or entity within a system that actors interact with or access.

Permission

Permission represents the relationship between a role and an actor or asset, requiring an external mapping to an asset. There are two types of permissions:

1. Actor permissions

   An Actor (e.g., user) is granted permission to an asset.

   Field	Field Type	Description
   actor_id	string	The unique identifier of the actor who has said permission
   role_code	string	The role code of the permission the actor has

2. Asset permissions

   An Asset (e.g., group) grants permission to another asset.

   Field	Field Type	Description
   asset_id	string	The unique identifier of the actor who has said permission
   role_code	string	The role code of the permission the actor has

Endpoints specification

Entitle's agent expects all responses to be in JSON format with the following structure:

ℹ️

Note

Entitle's agent expects a status code 200 for success. All other status codes will indicate a failure.

[GET] Get Actors

Request body: empty

Response: {'data': {'actors': <as below>}}

[GET] Get Assets

Request body: empty

Response:{'data': {'assets': <as below>}}

[GET] Get All Permissions

Request body: empty

Response: {'data': {'actor_permissions': <as below>, 'asset_permissions': <as below>}}

[GET] Get Asset Permissions

Path parameters: The URL we call will look like this - <get_asset_permissions_path>/{asset_identifier}

Request body: empty

Response: {'data': {'actor_permissions': <as below>, 'asset_permissions': <as below>}}

[POST] Give Access

The request body is in JSON format with the following fields:

Response: {'data': {}}

[POST] Revoke Access

The request body is in JSON format with the following fields:

Response: {'data': {}}

[POST] Check Config (optional)

The request body is in JSON format with the following fields:

Response: {'data': {'valid': <true/false>, 'reason': '<if the config is invalid, why?>'}}

[POST] Create actor (optional)

The request body is in JSON format with the following fields:

Response: {'data': {'actor': {'email': 'actor_mail', 'identifier': 'actor_id', 'name': 'actor_name', 'type': 'actor_type'}, 'login_info': {'username': 'test'}}}

[POST] Delete actor (optional)

The request body is in JSON format with the following fields:

Response: {}

Endpoints SWAGGER - visual presentation

Open API definition

For a more convenient view of this specification and to automatically generate code stubs in different languages, visit the Swagger Editor and input the following definition.

Example server for REST API integration

Click here to view an example of how an implemented HTTP server for REST API integration should look.

Create the integration in Entitle

💡

Important

This applies to creating an integration either through Entitle on Pathfinder or through the Entitle standalone product.

1. Sign in to Entitle.

2. Navigate to the Integrations page.

3. Click Add Integration.

4. In the Application field, enter REST API.

5. In the Save on dropdown, select Entitle cloud or your hosted agent.

6. In the Connection field, select one of the four available options within the two integration modes (Standing Accounts or Ephemeral Accounts).

7. Select/deselect the Allow changing account permissions and Allow creating accounts checkboxes according to your selection:

   

8. Choose whether you wish to specify full or relative paths:
   • Full path: To specify full paths, do not add schema and host to the configuration.
   • Relative path: To specify relative paths, add schema (”http”/”https”) and host (e.g., “yourhost.com”) to the final configuration:

"schema": "http", // http or https (optional)
"host": "yourhost.com", // the hostname which hosts your permissions server (optional)

9. Choose one of two options for authentication and authorization:

   • Option 1: OAuth
     • Client credentials flow according to the Client Credentials flow.
     • Under the oauth_data field, insert the relevant information.
       See the example below:
     JSON

     {
     	"schema": "http", // http or https (optional)
     	"host": "yourhost.com", // the hostname which hosts your permissions server (optional)
     	"get_actors_path": "/my_actors", // get actors will call GET 'yourhost.com/my_actors'
     	"get_assets_path": "/my_assets", // get assets will call GET 'yourhost.com/my_assets'
     	"get_all_permissions_path": "/perm", // get all permissions will call GET 'yourhost.com/perm'
     	"give_access_path": "/give", // give access will call POST 'yourhost.com/give"
     	"revoke_access_path": "/revoke", // revoke access will call POST 'yourhost.com/revoke"
     	"create_actor_path": "/create_actor", // create actor will call POST 'yourhost.com/create_actor"
       "delete_actor_path": "/delete_actor", // delete actor will call POST 'yourhost.com/delete_actor"
       "oauth_data": {
           "auth_server": "<http://myauth.company.com>",
           "client_id": "\\<CLIENT_ID>",
           "client_secret": "\\<CLIENT_SECRET>",
           "audience": "" //(optional)
       }
     }
     

   • Option 2: Token-based
     • Insert the token in the appropriate position under the headers field.
       See the example below:
     JSON

     {
     	"get_actors_path": "http://yourhost.com/my_actors", // get actors will call GET 'yourhost.com/my_actors'
     	"get_assets_path": "http://yourhost.com/my_assets", // get assets will call GET 'yourhost.com/my_assets'
     	"get_asset_permissions_path": "http://yourhost.com/perm", // get asset permissions will call GET 'yourhost.com/perm/{asset_identifier}'
     	"give_access_path": "http://yourhost.com/give", // give access will call POST 'yourhost.com/give"
     	"revoke_access_path": "http://yourhost.com/revoke", // revoke access will call POST 'yourhost.com/revoke"
     	"create_actor_path": "/create_actor", // create actor will call POST 'yourhost.com/create_actor"
       "delete_actor_path": "/delete_actor", // delete actor will call POST 'yourhost.com/delete_actor"
       "headers": {
           "Authorization": "Bearer <TOKEN>",
       }
     }
     

10. Example JSON configuration:

    

    ℹ️

    Note

    The configuration above reflects a combination of both integration modes—Standing Accounts and Ephemeral Accounts—since both Allow changing account permissions and Allow creating accounts checkboxes are enabled.