Skip to content

API v1 - Secret manager

Secret manager API endpoints allow you to import, export, post, and delete information stored in the Matillion ETL secret manager.

To use these endpoints, you must register for an account with your chosen cloud provider, so that you can reference passwords, API tokens, keys, and secrets stored in third-party secret manager platforms, such as AWS, Azure, and GCP. For more information, read Integrating Matillion ETL with Secret Managers.

You can manage your secret managers within Matillion ETL via Manage Project Group Passwords on the Project menu.

Prerequisites

  • To use Matillion ETL API services you require access to the Matillion ETL instance and should 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.
  • For more information about accessing the Matillion API, and general information on the Matillion API platform before using the API, read Matillion ETL API - v1.
  • Matillion ETL API endpoints require authorization to make any REST API call, so ensure a username and password for the Matillion ETL instance is configured before making any API call.

Using the API

Interact with the secret manager API in a Matillion ETL instance by making a GET, POST, or DELETE call with the form:

<InstanceAddress>/rest/v1/group/name/<groupName>/secretManager/<endpoint>

Where:

  • <instanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group using the secret manager.
  • <endpoint> is the name of the API endpoint that accomplishes the task you want to perform. These endpoints are documented in the following sections.

List secret managers

Return a list of all the secret managers listed in your Matillion ETL instance.

To list the secret managers, make the following GET call:

<InstanceAddress>/rest/v1/group/name/<groupName>/secretManager

A successful GET call to the endpoint will return a JSON response from the server, with the following format:

{
    "<secretManagerName>"
}

Export secret manager

Export details of secret managers in your Matillion ETL instance in a JSON format. This can be saved to a JSON file, or can be copied into the body of a POST import call for importing into the same or another Matillion ETL instance.

To export the secret manager details, make the following GET call:

<InstanceAddress>/rest/v1/group/name/<groupName>/secretManager/export

A successful GET call to the endpoint will return the following response from the server, in JSON format:

{
    "secretManagerName": "YourSecretManagerName",
    "secretManagerConfigExport": {
        "type": "YourCloudProvider_secret_manager_config_export",
        "credentialName": "YourCredentialsName",
        "region": "SecretManagerRegion"
    },
    "version": "YourBuildVersion",
    "environment": "Data Warehouse"
}
  • secretManagerName: The name of the secret manager within your Matillion ETL instance. Modify this name if you are going to import the details back into the same Matillion ETL instance to create a new secret manager.
  • secretManagerConfigExport: Contains the following parameters:
    • type: The third-party platform of your secret manager.
    • credentialName: The cloud provider credentials that are used to connect to your third-party platform secret manager.
    • region: (AWS Secret Manager only.) The AWS region within which your secret manager resource has been created.
  • version: Your Matillion ETL build.
  • environment: Details of the Matillion ETL environment used to execute jobs, such as the default Cloud Data Warehouse (CDW) database and schema.

Import secret manager

Import a secret managers configuration defined in a JSON file, into the specified Matillion ETL instance.

This is typically used to import secret managers you exported from one instance using the export endpoint into a new instance. An easy method of doing this is to copy the server response from the export endpoint, and paste it into the body of your import call.

To import the secret manager details, make the following POST call:

<InstanceAddress>/rest/v1/group/name/<groupName>/secretManager/import

This endpoint requires a POST body in the following form:

{
    "secretManagerName": "YourSecretManagerName",
    "secretManagerConfigExport": {
        "type": "YourCloudProvider_secret_manager_config_export",
        "credentialName": "YourCredentialsName",
        "region": "SecretManagerRegion"
    },
    "version": "YourBuildVersion",
    "environment": "Data Warehouse"
}
  • secretManagerName: The name of the secret manager within your Matillion ETL instance.
  • secretManagerConfigExport: Contains the following parameters:
    • type: The third-party platform of your secret manager.
    • credentialName: The cloud provider credentials that are used to connect to your third-party platform secret manager.
    • region: (AWS Secret Manager only.) The AWS region within which your secret manager resource has been created.
  • version: Your Matillion ETL build.
  • environment: Details of the Matillion ETL environment used to execute jobs, such as the default Cloud Data Warehouse (CDW) database and schema.

A successful POST call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "name": "<secretManagerName>"
}

To handle import conflicts occurring with this endpoint, there is an optional parameter you can add to the URL, called onConflict. This determines what happens when an import clashes with something that already exists, such as when you try to import a secret manager with the same name. The parameter has one of three values, defined as follows:

  • ERROR: Sends an error message back.
  • SKIP: Skips importing any clashes, and preserves the existing secret manager.
  • OVERWRITE: Removes the existing secret manager and replaces it with the newly imported secret manager.

An example of use is as follows:

<InstanceAddress>/rest/v1/group/name/<groupName>/secretManager/import?onConflict=SKIP

Delete secret manager

Deletes the specified secret manager in your Matillion ETL instance.

To delete the secret manager, make the following DELETE call:

<InstanceAddress>/rest/v1/group/name/<groupName>/secretManager/name/<secretManagerName>

Where <secretManagerName> is the name of the secret manager you wish to delete.

A successful DELETE call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "msg": "Successfully deleted secret manager <secretManagerName>",
    "id": 0
}