API v1 - Permission

The Permission API gives details on permissions that either allow or restrict access to each group in Matillion ETL.

The Permissions in Matillion ETL allow admins to specify what parts of the client each user has access to or restrictions, if any. To enable Permissions on the server, an Admin must ensure that the Security Configuration Admin → User Configuration is set to "Internal" or "External". That will allow admin to "Manage Groups" and "Manage Permissions" through the Admin menu. View Permissions is available through the Help menu and can be managed by both "Admins" and regular users.

Manage Permissions

The Permission API provides the "resource" data ("Resources" refers to the information returned by an API). These resources usually have various endpoints which are combined with multiple HTTP methods for each endpoint. The Permissions API family consist of some PATHs that combine with endpoint resources using HTTP methods: GET, POST, and DELETE.

Note

This document is part of a series on the Matillion ETL API - v1.
This process requires the Matillion ETL instance URL, and the username and password of a user with appropriate permissions.
Users responsible for experimenting with Matillion ETL API services require access to the Matillion ETL instance and ought to know how to make REST API calls either employing a REST API GUI client such as Postman or employing a command-line interface like cURL.
Permissions API will be available for the admin users of Matillion ETL.

Permission API Endpoints

API Base URL

http(s)://[InstanceAddress]/rest/v1/[permission]

API Endpoints and Function

The Permission API is available on standard REST-based APIs that uses HTTP or HTTPS request to GET and POST data. The Permission API service is accessed through the Uniform Resource Identifier (URI). All following references in this document will assume the API Base URL has been specified. The available API endpoints are listed below:

Method	Path	URI	Function
PATH/user
GET	/user	http://[InstanceAddress]/rest/v1/permission/user	Get the list of users.
GET	/user/export	http://[InstanceAddress]/rest/v1/permission/user/export	Export all users for the specific permission.
POST	/user/import	http://[InstanceAddress]/rest/v1/permission/user/import	Import one or more permission users.
POST	/user/userName/delete	http://[InstanceAddress]/rest/v1/permission/user/userName/delete	Delete the selected permission user.
PATH/user/name/[userName]/groups
GET	/userName/groups/ids	http://[InstanceAddress]/rest/v1/permission/user/userName/groups/ids	Get the set of group IDs assigned to the selected permission user.
GET	/userName/groups/get	http://[InstanceAddress]/rest/v1/permission/user/userName/group/get	Get the set of group names assigned to the selected permission user.
POST	/userName/groups/add	http://[InstanceAddress]/rest/v1/permission/user/userName/group/add	Add a group to the selected permission user.
POST	/userName/groups/remove	http://[InstanceAddress]/rest/v1/permission/user/userName/group/remove	Remove a group from selected permission user.
PATH/group
GET	/export	http://[InstanceAddress]/rest/v1/permission/group/export	Export one or more permission group.
POST	/import	http://[InstanceAddress]/rest/v1/permission/group/import	Import one or more permission group.
GET	/parent	http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/parent	Get the parent Group ID of the selected permission group.
GET	/groupname/export	http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/export	Export the selected permission group.
DELETE	/groupName	http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/delete	Delete the selected permission group via a HTTP DELETE request.
POST	/update	http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/update WITH POST DATA arg0	Update the selected permission group.
POST	/delete	http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/delete	Delete the selected permission group via a HTTP POST request.
PATH/[groupName]/roles
GET	/get	http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/roles/get	Get the list of roles assigned to the selected permission group.
POST	/add	http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/roles/get	Add a role to the selected permission group.
POST	/remove	http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/roles/remove WITH POST DATA arg0	Remove a role from the selected permission group.
PATH/global
POST	/import	http://[InstanceAddress]/rest/v1/permission/global/import WITH POST DATA arg0	Import one or more group permissions.
GET	/export	http://[InstanceAddress]/rest/v1/permission/global/export	Export all permissions for every group.
GET	/group	http://[InstanceAddress]/rest/v1/permission/global/group	List all group permission.
PATH/instance
PATH	/group	http://[InstanceAddress]/rest/v1/permission/global/instance?groupName=[groupName]	Get the permission of the selected instance using groupName.
PATH/group/name/groupName
GET	/export	http://[InstanceAddress]/rest/v1/permission/global/group/name/[groupName]/export	Export all permissions for the selected group.
GET	/permission	http://[InstanceAddress]/rest/v1/permission/global/group/name/[groupName]/permission	List permission in the selected group.
POST	/clear	http://[InstanceAddress]/rest/v1/permission/global/group/name/[groupName]/clear	Reset permissions for the selected group.
PATH/permission/name/[permissionName]
GET	/get	http://[InstanceAddress]/rest/v1/permission/global/group/name/[groupName]/permission/name/[permissionName]/get	Get the selected permission.
POST	/update	http:///rest/v1/permission/global/group/name//permission/name//update	Update the selected permission. (DEFAULT, GRANTED, FORBIDDEN).

Graphical Representation

To illustrate the Permission API, endpoints and methods, below is the graphical flow of the /permission endpoint showing possible PATH, GET , POST, and DELETE options.

Permission API Endpoint Flow

URL Parameters and Description

Below is the list of endpoint parameters and their brief description:

Parameters Name	Description
[InstanceAddress]	This is the server IP address or domain name.
[groupName]	The name of the group.
[permissionName]	The name of the permission created in Matillion ETL.
[user]	Gets the list of users.
[update]	This allows to update the selected permissions.
[get]	This property will get the permissions associated with the groups in the Matillion ETL instance.
[clear]	Resets the permissions.
[roles]	This defines the roles assigned to the permission.
[remove]	This will remove the selected property from the instance.

Endpoints and Server Response

This chapter describes the Permission APIs endpoints and examples. These APIs offers REST-based web service, offering ease of use and a flexible choice of programming language. These APIs can be used to access and analyse the permissions to access within the Matillion ETL instance.

Before working with any Permission endpoint call, we recommend that you understand the concept of PATH used in the Permission API family.

A PATH is a unit of a REST API that you can call. A PATH comprises HTTP Methods (GET/POST/DELETE) and a URL PATH that, when exposed, is combined with the base PATH URL (/rest/v1) of the API.

The Permission API family comprises of following PATHs:

PATH/user
- PATH/user/name/groups
PATH/group
- PATH/group/roles
PATH/global
- PATH/instance
- PATH/group/name/
  - PATH/permission/name/

The graphical view of the Permission API PATHs shown below:

Permission Endpoint PATH

Once you have a basic understanding of PATH and associated HTTP methods, you can start making API requests.

All the APIs listed in this chapter are available to use with GET/POST/DELETE methods to retrieve the "resource" information. The detailed description of each endpoint and associated methods is discussed in the next section of this guide.

PATH/user

This is a PATH for the user permissions within the Matillion ETL instance. This will provide the list of users assigned permissions for the instance.

List of endpoints for the PATH/user:

GET/user
GET/user/export
POST/user/import
POST/userName/delete
GET/userName/group/id
GET/userName/group/get
POST/userName/group/add
POST/userName/group/remove

GET/user

To get the list of users for the specified permission. This example using GET method REST API call to export the permission users.

Base URL

http://[InstanceAddress]/rest/v1/permission/user

Server Response

{
        "user-1"
        "user-2"
        "user-3"
}

GET/export

To export the list of users for the specific permission from one instance to another using /export endpoint. This example using GET method REST API call to export the permission groups and all associated information aligned with the groups.

Base URL

http://[InstanceAddress]/rest/v1/permission/user/export

Server Response

{
        "objects": [
            {
                "name": "automation-user",
                "groupNames": []
            },
            {
                "name": "ss-docs",
                "groupNames": []
            }
        ],
        "version": "Built",
        "environment": "redshift"
    }

POST/import

The /import endpoint imports one or more permission user. This example uses the POST method REST API call to import the permission users to the instance. Note that, when importing, there is no "merge" option. If a resource of the same name already exists, you must delete the existing resource before importing the new. This will be a POST method API call as we will have to attach the project (in JSON form, as exported), in the body as a JSON file to import into the Matillion ETL instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/user/import

POST BODY(JSON)

{
            "objects": [
                {
                    "name": "User-1",
                    "groupNames": []
                },
                {
                    "name": "User-2",
                    "groupNames": []
                }
            ],
            "version": "Built",
            "environment": "redshift"
        }

Server Response

{
        "name": "Permission Users",
        "statusList": [
            {
                "success": true,
                "name": "User-1"
            },
            {
                "success": true,
                "name": "User-2"
            }
        ],
        "success": true
    }

URL Parameters

There is an optional parameter, onConflict, which determines what should happen if an import clashes with something that already exists. For an explanation of this parameter's use, read API Import conflicts - Explanation in Matillion ETL API - v1.

POST/userName/delete

Delete the selected permission user from the instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/user/name/userName/delete

Server Response

{
"success": true,
"msg": "Successfully deleted the permission user by the name: User-1",
"id": -1
}

PATH/user/name/[userName]/groups

GET/userName/groups/ids

To get the set of group IDs assigned to the selected permission user. This example uses the GET method REST API call to export the groups' ids assigned to the user.

Base URL

http://[InstanceAddress]/rest/v1/permission/user/name/userName/groups/ids

Server Response

{
2138489
}

GET/userName/groups/get

Get the set of group names assigned to the selected permission user. This example uses the GET method REST API call to get the groups assigned to the user.

Base URL

http://<InstanceAddress>/rest/v1/permission/user/name/userName/groups/get

Server Response

{
"Runner",
"Scheduler",
"Reader with Comments",
"All Global Access",
"Reader",
"Writer"
}

POST/userName/groups/add

This is to add a group to the selected permission user. If a resource of the same name already exists, you must delete the existing resource before adding the new. This will be a POST method API call as we will have to attach the details in the body as a JSON to add a group into the instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/user/name/userName/groups/add

POST Body (JSON)

{
"name": "Test"
}

Server Response

{
"success": true,
"msg": "Successfully added the group permission Test to the group.",
"id": -1
}

POST/userName/groups/remove

This is to remove a group from the selected permission group.

Base URL

http://[InstanceAddress]/rest/v1/permission/user/name/userName/groups/remove

Server Response

{
"success": true,
"msg": "Successfully removed the group permission Test.",
"id": -1
}

PATH/group

PATH/group is a primary PATH for the API Base URL of Permission API aligned with HTTP methods (GET, POST, DELETE), and a PATH to make a unique operation for the resource to retrieve the information correlated with the permissions associated with the groups in the instance.

List of endpoints for the PATH/group:

GET/export
POST/import
GET/parent
GET/groupName/export
DELETE/groupName
POST/update
POST/delete
PATH/roles

GET/export

To export one or more permission groups within the Matillion ETL instance, use /export endpoint. This example uses the GET method REST API call to export the permission groups and all associated information aligned with the groups.

Base URL

http://[InstanceAddress]/rest/v1/permission/group/export

Server Response

{
"objects": [
{
"name": "Writer",
"otherRoles": [],
"parentGroupID": null
},
{
"name": "NoEnterprise",
"otherRoles": [],
"parentGroupID": null
},
{
"name": "Runner",
"otherRoles": [],
"parentGroupID": null
}.....
],
"version": "1.48.7",
"environment": "redshift"
}

POST/import

Now that you have an exported permission group (see previous example), we'll use the API to import one or more permission groups into a Matillion ETL instance. Note that, when importing, there is no "merge" option. If a resource of the same name already exists, you must delete the existing resource before importing the new. This will be a POST method API call as we will have to attach the project (in JSON form, as exported), in the body as a JSON file to import into the Matillion ETL instance.

Base URL

http://[InstanceAddres]>/rest/v1/permission/group/import

POST BODY(JSON)

{
"objects": [
{
"name": "Docs",
"otherRoles": [],
"parentGroupID": null
}
],
"version": "1.48.7",
"environment": "redshift"
}

Server Response

{
"name": "Permission Groups",
"statusList": [
{
"success": true,
"name": "Docs"
}
],
"success": true
}

URL Parameters

There is an optional parameter, onConflict, which determines what should happen if an import clashes with something that already exists. For an explanation of this parameter's use, read API Import conflicts - Explanation in Matillion ETL API - v1.

GET/parent

This example is a GET method REST API request that will provide the parent Group ID of the selected permission group within the Matillion ETL instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/parent

Server Response

{
123456
}

GET/[groupName]/export

To export the all group permissions within the instance, provide the groupName and use the /export endpoint. This example uses the GET method REST API call to export the selected permission group and all associated information aligned with the group.

Base URL

http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/export

Server Response

{
        "objects": [
            {
                "name": "Example-Group",
                "otherRoles": [],
                "parentGroupID": null
            }
        ],
        "version": "1.44.11",
        "environment": "redshift"
    }

DELETE/groupName

To remove any resource from the list, use the DELETE API request. In this example, we'll delete a permission group from within the permissions in the Matillion ETL instance.

Note

There are often multiple ways of achieving the same task within the API as resources and methods branch out and overlap.

Base URL

http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]

Server Response

{
      "success": true,
      "msg": "Successfully deleted schedule [Exampleschedule]",
      "id": -1
    }

POST/update

The /update endpoint will allow to update the selected permission group. This will be a POST method API call as you'll need to attach the project (in JSON form, as exported), in the body as a JSON file to import into the Matillion ETL instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/update WITH POST DATA arg0

POST BODY(JSON)

{
                "name": "Writer",
                "otherRoles": [],
                "parentGroupID": null
    }

Below is the description of the fields included in the POST body:

Field name	Data type	Description
name	String	The name of the permission group.
otherRoles	String	The new role if required to be added.
parentGroupID	String	The id of the parent group, if available.

Server Response

{
      "success": true,
      "msg": "Successfully updated the permission group: Writer",
      "id": -1
    }

POST/delete

This will be a POST method API call. The /delete endpoint will delete the selected permission group.

Base URL

http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/delete

Server Response

{
      "success": true,
      "msg": "Successfully deleted the permission group: test",
      "id": -1
    }

PATH/[groupName]/roles

PATH/roles is a part of the primary PATH/group of Permission API aligned with two HTTP method (GET and POST) to make a unique operation for the resource to retrieve the information correlated with the permissions associatd with the groups in the instance.

List of endpoints for the PATH/roles:

GET/get
POST/add
POST/remove

GET/get

This is a GET request API call to retrieve the list of roles assigned to the selected permissions group.

Base URL

http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/roles/get

Server Response

{
        "API",
        "Admin"
}

POST/add

This API endpoint call is to add a role to the selected permission group. This will be a POST method API call as we will have to attach the role in the body as a TEXT file to import into the Matillion ETL instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/roles/add WITH POST DATA arg0

POST BODY

{
     "name":"Global"     
    }

Server Response

{
      "success": true,
      "msg": "Successfully assigned the role [{\\r\
 \\"name\\":\\"Global\\"     \\r\
}] to the group [Writer].",
      "id": -1
    }

POST/remove

This is a POST request API call to remove a role from the selected permission group.

Base URL

http://[InstanceAddress]/rest/v1/permission/group/name/[groupName]/roles/remove WITH POST DATA arg0

POST BODY

{
     "name":"Global"     
    }

Server Response

{
      "success": true,
      "msg": "Successfully removed the role [{\\r\
 \\"name\\":\\"Global\\"     \\r\
}] from the group [Writer].",
      "id": -1
    }

PATH/global

PATH/global is a part of the Permission API family with HTTP methods (GET and POST) and two PATH to make a unique operation for the resource to retrieve the information correlated with the permissions associated with the groups in the instance.

List of endpoints for the PATH/global:

GET/export
GET/group
POST/import
PATH/instance
PATH/group/name/[groupName]

GET/export

The is a GET operation for the resource information to export all the permissions for every group within the instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/global/export

Server Response

{
        "objects": [
              {
                "group": "Example-Group",
                "permissions": {
                    "": "GRANTED",
                    "/OAuth": "GRANTED",
                    "/Variable": "GRANTED",
                    "/CDC": "GRANTED",
                    "/API Profile/Read": "GRANTED",
                    "/API Profile": "GRANTED",
                    "/Project": "GRANTED",
                    "/CDC/Read": "GRANTED",
                    "/CDC/Write": "GRANTED",
                    "/Credential": "GRANTED",
                    "/API Profile/Write": "GRANTED",
                    "/Queue": "GRANTED",
                    "/Password": "FORBIDDEN"
                }
            },
        ],
        "version": "1.44.11",
        "environment": "redshift"
    }

GET/group

This endpoint retrieve the list of all permissions for every group in the instance, using GET REST API call.

Base URL

http://[InstanceAddress]/rest/v1/permission/global/group

Server Response

{
        "Example-Group",
        "Example-Group-2",
        "Admin only",
        "Reader",
}

POST/import

Now that you have an exported permission group (see previous example), we'll use the API to import the group into a Matillion ETL instance. Note that, when importing, there is no "merge" option. If a resource of the same name already exists, you must delete the existing resource before importing the new. This will be a POST method API call as we will have to attach the project (in JSON form, as exported), in the body as a JSON file to import into the Matillion ETL instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/global/import

POST BODY(JSON)

{
        "objects": [
              {
                "group": "Example-Group",
                "permissions": {
                    "": "GRANTED",
                    "/OAuth": "GRANTED",
                    "/Variable": "GRANTED",
                    "/CDC": "GRANTED",
                    "/API Profile/Read": "GRANTED",
                    "/API Profile": "GRANTED",
                    "/Project": "GRANTED",
                    "/CDC/Read": "GRANTED",
                    "/CDC/Write": "GRANTED",
                    "/Credential": "GRANTED",
                    "/API Profile/Write": "GRANTED",
                    "/Queue": "GRANTED",
                    "/Password": "FORBIDDEN"
                }
            },
        ],
        "version": "1.44.11",
        "environment": "redshift"
    }

Server Response

{
      "name": "Group Permissions",
      "statusList": [
        {
          "success": true,
          "name": "Example-Group"
        },
      ],
    }

PATH/instance

We'll be retrieving a single resource information, performing a GET request for that named resource endpoint. This PATH is a part of the PATH/global URI which will retrieve the global list of groups for the instance.

When you reach a named resource endpoint, the API will expose API metadata for that resource, including PATH, GET and POST and DELETE method options available.

Base URL

http://[InstanceAddress]/rest/v1/permission/global/instance?groupName=[groupName]

Server Response

{
      "endpoints": [
        {
          "httpMethod": "PATH",
          "name": "GroupPermissionInstanceService",
          "children": [
            {
              "httpMethod": "GET",
              "name": "exportPermissions",
              "description": "Export all permissions for the selected group.",
              "path": "/export",
              "type": "ExportContainer<GroupPermissionContainerExport>",
              "example": "/export",
              "totalPath": "/export"
            },
            {
              "httpMethod": "GET",
              "name": "listPermissions",
              "description": "List permission in the selected group.",
              "path": "/permission",
              "type": "Set<String>",
              "example": "/permission",
              "totalPath": "/permission"
            },
              ],
              "children": [],
      "dataTypes": []
        } ]
    }

PATH/group/name/[groupName]

PATH/group/name{group} is a part of the PATH/global URI family with twto HTTP methods (GET and POST), and one PATH, for the resource to retrieve the information correlating with the permissions of the groups within the instance.

List of endpoints for the PATH/group/name/[groupName]:

GET/export
GET/permission
POST/clear
[PATH//permission/name/permissionName

GET/export

The is a GET operation for the resource information to export all the permissions for the selected group within the instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/global/group/name/[groupName]/export

Server Response

{
        "objects": [
              {
                "group": "Example-Group",
                "permissions": {
                    "": "GRANTED",
                    "/OAuth": "GRANTED",
                    "/Variable": "GRANTED",
                    "/CDC": "GRANTED",
                    "/API Profile/Read": "GRANTED",
                    "/API Profile": "GRANTED",
                    "/Project": "GRANTED",
                    "/CDC/Read": "GRANTED",
                    "/CDC/Write": "GRANTED",
                    "/Credential": "GRANTED",
                    "/API Profile/Write": "GRANTED",
                    "/Queue": "GRANTED",
                    "/Password": "FORBIDDEN"
                }
            },
        ],
        "version": "1.44.11",
        "environment": "redshift"
    }

GET/permission

This endpoint retrieves the list of all permissions aligned with the selected group within the instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/global/group/name/[groupName]/permission

Server Response

{
        "Project",
        "Credential",
        "Variable",
        "CDC",
        "API Profile",
        "CDC-Write",
        "API Profile-Read",
        "CDC-Read",
        "Queue",
        "OAuth",
        "API Profile-Write",
        "Password"
}

POST/clear

This API call lets you reset permissions for the selected group within the Matillion ETL instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/global/group/name/[groupName]/clear

Server Response

{
      "success": true,
      "msg": "Successfully reset the permissions for the group: Example-Group",
      "id": -1
    }

PATH/permission/name/[permissionName]

This PATH is a part of the PATH/group/name/[groupName] URI, with two HTTP methods (GET and POST), to make a unique operation for the resource to retrieve or update the information associated within the instance.

List of endpoints for the PATH/permission/name/[permissionName]:

GET/get
POST/update

GET/get

This endpoint is a GET request API call that lets you retrieve the information of the selected permissions for the instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/global/group/name/[groupName]/permission/name/[permissionName]/get

Server Response

{
      "id": "/APIProfile",
      "state": "GRANTED"
    }

POST/update

The endpoint will update the state of selected permissions from the selected group within the instance. There are three permissions in Matillion ETL instance: DEFAULT, GRANTED, FORBIDDEN. This will be a POST method API call as we will have to attach the project (in JSON form, as exported), in the body as a JSON file to import into the Matillion ETL instance.

Base URL

http://[InstanceAddress]/rest/v1/permission/global/group/name/[groupName]/permission/name/[permissionName]/update WITH POST DATA arg0

POST BODY(JSON)

{
          "id": "/APIProfile",
          "state": "FORBIDDEN"
    }

Below is the description of the fields included in the POST body:

Field name	Data type	Description
id	String	The name of the permission as available in instance.
state	String	The new state to be changed. Must be one of: DEFAULT, FORBIDDEN, or GRANTED.

Server Response

{
        "success": true,
        "msg": "Successfully update the state of the permission: APIProfile",
        "id": 0
    }