Skip to content

API v1 - Passwords

Overview

This is a guide to providing details on the Password API from the family of the Group API . The Password endpoint allows users to explore and manage the passwords of the Project Group within the Matillion ETL. Passwords are stored at the Project Group level and thus will be shared with, and accessible from, all other projects within that same group.​

Password API (PATH/password) is a part of the /group API as shown below:

Group endpoint PATHs

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

Manage Passwords

The Password API provides the "resource" details within the Project Group of your Matillion ETL instance. By "resources", we refer to exploring and managing the passwords, such as get and list, export/import and update, delete, and create a new password within your Matillion ETL instance. The Password endpoint is the part of the /group API family with many endpoints that include HTTP methods (GET, POST, and DELETE) for unique combinations to get the "resource" information for your Matillion ETL instance.

Important Information

  • This document is part of a series on API v1 - Group and the Matillion ETL API - v1.
  • 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.
  • Matillion ETL API endpoints require authorisation to make any REST API call, so ensure a username and password for the Matillion ETL instance is configured before making any API call.

Password API Endpoints

API Base URL

http(s)://<InstanceAddress>/rest/v1/group/name/<groupName>/password

API Endpoints and Function

Password API endpoint is available on standard REST-based APIs that uses HTTP or HTTPS request to GET, POST, and DELETE data. The Password API service is accessed through the Uniform Resource Identifier (URI). The available API endpoints are listed below:

Method Path URI Function
GET /name http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/name Get the name of the password.
GET /id http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/id Gets the ID of the password.
GET /get http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/get Returns the password.
GET /export http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/export Export the given password.
POST /delete http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/delete Delete the given password.
POST /updateFromExport http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/updateFromExport WITH POST DATA arg0 Supply password as already encoded since password will be created as is.
POST /create http://<instance address>/rest/v1/group/name/<groupname>/password/create Supply password as plaintext to be Encoded by standard set in EncryptionType.
POST /import http://<instance address>/rest/v1/group/name/<groupname>/password/import Import password via ExportContainer. Supply password as already encoded since password will be created as is.​
POST /update http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/update WITH POST DATA arg0 Supply password as plaintext as it will encode via encryptionType provided.
DELETE /passwordName http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName To delete the selected version using DELETE HTTP method.

Graphical Representation

To illustrate the Password API v1, endpoints and methods to the further, below is the graphical flow of the /password endpoint showing possible PATH, GET , POST, and DELETE options.

Password endpoint Flow


URL Parameters and Description

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

Parameters Name Description
<instance address> This is the server IP address or domain name.
<groupName> The name of the group.
<passwordName> The name of the password available within the Project Group.
<export> This allows to export the metadata of the resource.
<import> This allows to import the metadata of the resource.
<delete> Delete the selected resource.
<id> The queue id of the current resource.
<name> The name of the selected resource.
<create> To create a new resource using POST body.
<update> To update or supply the resource details using POST body.

Endpoints and Server Response

This chapter describes the Password API endpoints with examples. These APIs offers REST-based web service, offering ease of use and a flexible choice of programming language.

All the APIs listed in this chapter are available to use with GET/POST/DELETE methods to retrieve the data used to get, update, import/export, create or delete the passwords within the Project Group.

List of endpoints for the /password:

Below is the detailed description of these endpoints with example response from the server.

GET/name

This is a GET method REST API request that will provide the name of the password within the Project Group of the Matillion ETL instance.

  • Base URL 
    http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/name
  • Server Response 
    API PROJECT-test

GET/id

This is to get the ID of the selected password from the the current Project Group. The API call is a GET HTTP method request to fetch the detail.

  • Base URL 
    http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/id
  • Server Response 
    71682

GET/get

This API call is a GET HTTP method request that returns with the password detail, such as id, name, encyryprionType, password and description.

  • Base URL 
    http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/get
  • Server Response 
    {
  "id": 71682,
  "name": "API PROJECT-test",
  "password": "",
  "encryptionType": "ENCODED",
  "description": "Password for environment [test]."
}

GET/export

To export the password, provide the /passwordName and use the /export endpoint. This will export the selected password using GET HTTP method call request.

  • Base URL 
    http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/export
  • Server Response 
    {
    "objects": [
        {
            "name": "API PROJECT-test",
            "password": "",
            "masterKey": null,
            "description": "Password for environment [test].",
            "encryptionType": "ENCODED",
            "extraInfo": null
        }
    ],
    "version": "master",
    "environment": "redshift"
}

POST/delete

This will be a POST method API call. The /delete endpoint will allow to delete the selected password from the Project Group in the instance.

  • Base URL 
    http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/delete
  • Server Response 
    {
  "success": true,
  "msg": "Successfully deleted the password: API PROJECT-test",
  "id": -1
}

POST/updateFromExport

Supply password as already encoded and password will be created as is. This will be a POST method API call as we will have to attach the variable for the passwords to be queued, in the body as a JSON file to run into the Matillion ETL instance.

  • Base URL 
    http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/updateFromExport WITH POST DATA arg0
  • POST Body 
    {
            "name": "API PROJECT-test",
            "password": "test",
            "masterKey": null,
            "description": "Password for environment [test].",
            "encryptionType": "ENCODED",
            "extraInfo": null
        }

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

    Field name Data type Description
    name String An arbitrary name of the password.
    password String Provide an arbitrary password.
    masterKey String An AWS KMS Master Key that will be used to encrypt the password. It can be same as you get in exporting the password detail.
    description String An optional description of this password.
    encryptionType String Choose between "ENCODED" and the key management service the platform offers ("KMS" or "KVS"). Preferably keep as "ENCODED"
    extraInfo String Some additional description if needed.
  • Server Response 
    {
  "success": true,
  "msg": "Successfully updated password: API PROJECT-test.",
  "id": 71682
}

Please Note

Modifying the "Password Name" is not allowed in POST Body, please keep the password name same as in URL <passwordName>

POST/create

This is to supply password as plaintext to be Encoded by standard set in EncryptionType.

  • Base URL 
    http://<instance address>/rest/v1/group/name/<groupname>/password/create
  • POST Body 
    {
            "name": "test-password",
            "password": "test01",
            "masterKey": null,
            "description": "Password for environment [test].",
            "encryptionType": "ENCODED",
            "extraInfo": null
}
  • Server Response 
    {
  "success": true,
  "msg": "Successfully created password: test-password",
  "id": 66329
}

Please Note

The description of the field names used in POST body, please refer the section above.

POST/import

Now you have already export the password in the example before. This time is to import password via ExportContainer. Supply password as already encoded since password will be created as is. This will be a POST method API call as we will have to attach the variable for the password to be imported, in the body as a JSON file to run into the Matillion ETL instance.

Please Note

If a resource of the same name already exists, you must delete the existing resource before importing the new or you can change the name of the imported resource (passwordImported) in the POST BODY.

  • Base URL 
    http://<instance address>/rest/v1/group/name/<groupname>/password/import
  • POST Body 
    {    
    "objects": [
        {
            "name": "PasswordImported",
            "password": "test",
            "masterKey": null,
            "description": "Password for environment [test].",
            "encryptionType": "ENCODED",
            "extraInfo": null
        }
    ],
    "version": "master",
    "environment": "redshift"
}
  • Server Response 
    {
  "name": "Passwords",
  "statusList": [
    {
      "success": true,
      "name": "PasswordImported"
    }
  ],
  "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.

Please Note

The description of the field names used in POST body, please refer the section above.

POST/update

The POST HTTP method API call request is to supply password as plaintext as it will encode via encryptionType provided.

  • Base URL 
    http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/update WITH POST DATA arg0
  • POST Body 
    {
            "name": "API PROJECT-test",
            "password": "test01",
            "masterKey": null,
            "description": "Password for environment [test].",
            "encryptionType": "ENCODED",
            "extraInfo": null
}
  • Server Response 
    {
  "success": true,
  "msg": "Successfully updated password: API PROJECT-test.",
  "id": 71682
}

Please Note

Modifying the "Password Name" is not allowed in POST Body, please keep the password name same as in URL <passwordName>

For the description of the field names used in POST body, please refer the section above.

DELETE/passwordName

The DELETE HTTP request will allow to delete the selected password from the Project Group within the instance.

  • Base URL 
    http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>
  • Server Response 
    {
  "success": true,
  "msg": "Successfully deleted password: API PROJECT-test",
  "id": 0
}
© Copyright 2024 Matillion Ltd | Legal | Privacy Policy | Disclaimer | Modern Slavery Statement