API v1 - Passwords

API v1 - Passwords


This article is part of a series on the v1 API.


Overview



Passwords are typically managed using the Manage Passwords menu inside the Matillion ETL client. It is, however, possible to perform many similar functions through the v1 API.

Since Passwords in the Matillion ETL client are specific a Project Group (and thus are shared with and accessible from all Projects within that same Group), the Password API endpoint can be found within the Group endpoint:

<InstanceAddress>/rest/v1/group/name/<GroupName>/password


Below, we briefly discuss and give examples of common tasks that can be accomplished through the Passwords endpoint.

Examples will be given as cURL commands and all follow a similar pattern:

curl -X GET -o filename.json -u user:password http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/


Where:

  • GET can be any RESTful command. The Matillion v1 API makes most use of GET, POST and DELETE
  • filename.json is an arbitrarily-named JSON file. In the above case, it holds the output (-o flag) of our GET command.
    • POST commands often require a JSON for input, specified after the --data-binary flag.
  • user:password are the instance credentials attached to this cURL command. They MUST correspond to a valid username/password combination on the Matillion ETL instance that has API privileges.
  • http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/  is the full address of the desired endpoint. Angled brackets denote sections to be filled in accordingly by the user.
 

Password Encryption


Plaintext password data is NEVER stored in or available through the Matillion ETL client or its API. By default, passwords stored in Matillion ETL are stored as a SHA512 Hash of the plaintext, which can be used to check whether a given password is correct but cannot be used to derive the original password.

Certain API functions, such as importing passwords, will expect the SHA512 Hash and not the original plaintext. Thus if manually editing a password into an import file, you will be required to first convert your plaintext password to a SHA512 Hash using one of many common online tools. e.g.

Plaintext: password123
SHA512 Hash: 2dbeed8c6f230881f8b3fb7e676e238120329c013370e6cba8be929cf3df2a7fab19bb8b30f4b92388d8bd3476b4f3cf4af425f84b0bd580647d810a730f4ff6


Listing Passwords



Simply following the password endpoint will give you a complete list of all password names available in the specific project group. Such as via your browser as shown below (where the Group name is Test):

The cURL command below will achieve the same result:


curl -X GET -o passwordnames.json -u user:password http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/

  

Getting password information



Using a password's name, you can use the API to retrieve information about it, as below:


curl -X GET -o passwordnames.json -u user:password http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/name/<PasswordName>/get


This will yield a small JSON with details of that password entry, such as the example below:


{
   "id": 37391,
   "name": "DOCAPI",
   "password": "MjE0MzU=",
   "encryptionType": "ENCODED",
   "description": ""
}


Password details can be similarly recovered using the ID seen in the above example:


curl -X GET -o passwordnames.json -u user:password http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/id/<PasswordID>/get


If you know the name of a password and only want to knows its ID, you can use:


curl -X GET -o passwordnames.json -u user:password http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/name/<PasswordName>/id

 

Deleting Passwords



This is possible in two ways. Either using a DELETE command:


curl -X DELETE -u user:password http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/name/<PasswordName>


Or using a POST command:


curl -X POST -u user:password http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/name/<PasswordName>/delete

 

Exporting Passwords



Specific passwords can be exported by including that Password's name in the included path:


curl -X GET -o password.json -u user:password http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/name/DOCAPI/export


All passwords within a Group can be exported at once using:


curl -X GET -o passwords.json -u user:password http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/export

 

Importing Passwords



Passwords can be imported (in any amount) using:


curl -X POST -u user:password http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/import -H "Content-Type: application/json" --data-binary @passwords.json

 

  • Useful for transferring all passwords from an existing Matillion ETL instance to a new instance.
  • Password is to be given as encrypted (as they are exported encrypted).
  • Will error if you give a name that already exists as a password on the instance.

A new Password can be created using:

cURL POST -u user:password  http://<InstanceAddress>/rest/v1/group/name/Test/password/create -H "Content-Type: application/json" --data-binary @password.json


This time, the password data is given as a single password a format such as:


{
   "name": "NEWNAME",
   "password": "PASSWORD",
   "masterKey": null,
   "description": "",
   "encryptionType": "ENCODED"
}

  • Try exporting a specific password you'd like to emulate the format of to find the correct properties.
  • Password is to be given as plaintext. Matillion ETL will encrypt this immediately.
  • Will error if you give a name that already exists as a password on the instance.
 

Updating a password



Passwords can be updated in one of two ways: Using encoded or plaintext data. The former is generally used when updating a password using a export from another instance and so is termed an "Update from Export". The latter is generally used when wanting to manually change a password to something memorable (for example, if a user has forgotten their password).

Encoded:


curl -X POST -u user:password http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/name/<PasswordName>/updateFromExport -H "Content-Type: application/json" --data-binary @password.json



Plaintext:


curl -X POST -u user:password http://<InstanceAddress>/rest/v1/group/name/<GroupName>/password/name/<PasswordName>/update -H "Content-Type: application/json" --data-binary @password.json