Skip to content

Managing users, passwords, groups, and permissions

The Matillion ETL API provides a programmatic method of communicating with your instances. The API can be useful when you need to make quick changes and to check information. User configuration is essential for assigning roles, as well as creating, exporting, and removing entries where possible.

This article will guide 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 app, you can use the API to retrieve a list of users, export a list of user configurations, and import user configurations. You can also get user information for a specific user.

First, let's create some users on Matillion ETL. For detailed instructions, read User configuration.

Users listed with their assigned roles

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 call 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 app, but can also be managed through the API. The API enables you to get the name and ID of a password, as well as create, import, and delete passwords.

To get a password within a Project Group, input the following into Postman, replacing {GroupName} with your Project Group name:

GET https://{Instance address}/rest/v1/group/name/{GroupName}/password/name/

You can add the following endpoints to get more information about your password, replacing {PasswordName} with 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 and supply a password as plaintext in the body:

POST https://{Instance address}/rest/v1/group/name/{GroupName}/password/create

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 a password using the DELETE method:

DELETE https://{Instance address}/rest/v1/group/name/{GroupName}/password/name/{PasswordName}

Groups

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

Groups in Matillion ETL

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:

Group structure

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 along with the data in the body of your request:

POST https://{InstanceAddress}/rest/v1/group/import

For more information on what you can do with the /group endpoint, including importing and exporting specific resources, versions, and jobs, read API v1 - Group/project.

Permissions

Permissions are set through 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 app has granular permissions for the various aspects of the app, e.g. credentials, OAuth, passwords, shared jobs, and task history.

Permissions configuration

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 with the following URL and body. Replace otherRoles with a new role. The field type is a string.

POST https://{InstanceAddress}/rest/v1/permission/group/name/{GroupName}/update

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

To add a role to a specified permission group, use the following URL and body:

POST http://{InstanceAddress}/rest/v1/permission/group/name/{GroupName}/roles/add

{
 "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}

For a comprehensive list of what you can do with the Permissions API, including importing, retrieving single source information, and updating a permission, read API v1 - Permission.

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