Skip to content

Managing users, passwords, groups, and permissions

Overview

The Matillion ETL API provides another way to communicate with your instances, through the API interface. It is very useful when you need to make quick changes and check information. User configuration is essential for assigning roles, as well as creating, exporting, and removing entries where possible.

This article will step you through configuring users, passwords, groups, and permissions, using the Matillion API. We recommend using Postman to do this. To get started, Postman requires:

  • Your instance IP address
  • Your instance username
  • Your instance password

User configuration

After setting up users in the Matillion ETL client, you can use the API to retrieve a list of users, export a list of user configuration, and import user configuration. You can also get user information for a specific user.

First, let's create some users on Matillion ETL. For detailed instructions, please see here.

Next, we will use the API to retrieve and export the list of users.

In Postman, enter the following:

GET https://<InstanceAddress>/rest/v1/userconfig/user

The API calls returns the following:

[
    {
        "name": "automation-user",
        "admin": true,
        "api": true,
        "projectAdmin": false,
        "readOnly": false,
        "currentLoggedInUser": false
    },
    {
        "name": "private-name",
        "admin": true,
        "api": true,
        "projectAdmin": true,
        "readOnly": false,
        "currentLoggedInUser": true
    },
    {
        "name": "AnotherUser",
        "admin": true,
        "api": true,
        "projectAdmin": false,
        "readOnly": false,
        "currentLoggedInUser": false
    },
    {
        "name": "TestUser",
        "admin": true,
        "api": true,
        "projectAdmin": false,
        "readOnly": false,
        "currentLoggedInUser": false
    }
]

To export your users, enter the following:

GET https://<InstanceAddress>/rest/v1/userconfig/export

To import user data, we will need to use the POST method, along with a body of content, typically written in JSON or XML:

POST https://<InstanceAddress>/rest/v1/userconfig/import

{
    "objects": [
        {
            "type": "Internal",
            "users": [
                {
                    "username": "SampleUser",
                    "password": "testpassword",
                    "isServerAdmin": true,
                    "isApi": true,
                    "isProjectAdmin": true
                },
                {
                    "username": "OneMoreUser",
                    "password": "testpassword",
                    "isServerAdmin": true,
                    "isApi": false,
                    "isProjectAdmin": false
                }
                    ]
        }
    ],
    "version": "1.51.5",
    "environment": "redshift"
}

As you can see, you can configure whether the user has Server Admin, API, and Project Admin permissions.

You will receive the following response from the server:

{
    "name": "User Configuration",
    "statusList": [
        {
            "success": true,
            "name": "Internal"
        }
    ],
    "success": true
}

Passwords

Passwords are typically managed via the Password Manager in the Matillion ETL client, but can also be managed through the API. The API enables you to get the name and ID of a password, as well as creating, importing, and deleting a password.

To get a password within a Project Group, input the following into Postman:

GET https://<instance address>/rest/v1/group/name/<groupname>/password/name/

where <groupname> is your Project Group name.

You can add the following endpoints to get more information about your password (where <passwordName> is your password):

  • <passwordName>/id - the password ID
  • <passwordName>/export - to export the given password

To delete a password using POST, enter the following:

POST https://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/delete

To create a password, enter the following:

POST https://<instance address>/rest/v1/group/name/<groupname>/password/create

and supply a password as plaintext in the body.

You can add the following endpoints to manipulate your password further:

  • /import - to import a password via the ExportContainer
  • /update - to rename a password (supply as plaintext in the body)

You can also delete using the DELETE method:

DELETE https://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>

Groups

Groups are created in the Matillion ETL client by admin users only. There are several default options included (each has more permissions than the previous): Reader, Reading with Comments, Runner, Scheduler, and Writer. These groups come with various permissions that are applied to a user.

The Group API is a large endpoint that explores jobs, tasks, environments, versions, projects, groups, and passwords.

The Group API endpoint branches into different PATHs, but we will be looking at project groups in particular. The API follows a tree-like structure, in which the very last endpoint relates to individual jobs. Visually, it would look like this:

To get a list of groups in your instance, enter the following:

GET https://<instance address>/rest/v1/group

The server will respond with the following:

[
    "aws-redshift",
    "TestGroup",
    "UserGroup"
]

To access a specific group, input the following:

GET https://<instance address>/rest/v1/group/name/<groupName>

To see what Projects are available in your selected group, use the /project endpoint in your API call:

GET https://<InstanceAddress>/rest/v1/group/name/<groupName>/project

You can then use the /version endpoint to retrieve the version within your instance:

GET https://<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version

If you are looking for a job within a version of your project, use the /job endpoint:

GET https://<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/job

You can further refer to a specific job:

GET https://<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/job/name/<jobName>

To export your project, input the following:

GET https://<InstanceAddress>/rest/v1/group/export

To import an exported Project Group, use the POST method:

POST https://<InstanceAddress>/rest/v1/group/import

along with the data in the body of your request.

For more information on what you can do with the /group endpoint, including importing and exporting specific resources, versions, and jobs, please see here.

Permissions

Permissions are set through the Matillion ETL. The Matillion API allows you to get information about the permissions for each group, export a permission group, and update a specified permission group.

The Matillion ETL client has granular permissions for the various aspects of the client, e.g. credentials, OAuth, passwords, shared jobs, task history, etc.

To get the list of users in your instance, input the following:

GET https://<InstanceAddress>/rest/v1/permission/user

The server will send back the following response:

[
    "TestUser",
    "AnotherUser",
    "automation-user",
    "private-user",
    "OneMoreUser",
    "SampleUser"
]

To retrieve the list of roles assigned to a selected permissions group, enter the following:

GET https://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/roles/get

To export the selected permission group, enter the following:

GET https://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/export

To update the selected permission group, we will use the POST method:

POST https//<InstanceAddress>/rest/v1/permission/group/name/<groupName>/update

with the following JSON body:

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

where otherRoles is a new role. The field type is a string.

To add a role to a specified permission group, input:

POST http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/roles/add

with the post body of:

{
 "name":"Global"     
}

The server will return the following:

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

To delete a permission group from within the instance, we will use the DELETE method:

DELETE http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>

A comprehensive list of what you can do with the Permissions API, including importing, retrieving single source information, and updating a permission can be found here.

© Copyright 2024 Matillion Ltd | Legal | Privacy Policy | Disclaimer | Modern Slavery Statement