API v1 - Private key🔗

The Private key API allows you to create and securely store a private key, such as an SSH key, within a Project Group in your Matillion ETL instance. Private keys are stored at the Project Group level and are shared with, and accessible from, all projects within that group.

Note

The privateKey and passphrase values are never returned in API responses. You don't need to supply a private key type—Matillion ETL derives it automatically from the key content.

Prerequisites🔗

This document is part of a series on API v1 - Group/project and the Matillion ETL API - v1.
To use Matillion ETL API services, you must know how to make REST API calls, either by employing a REST API GUI client such as Postman, or employing a command line interface (CLI) like cURL.
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.
Private keys created with this API are used wherever Matillion ETL prompts for a private key and passphrase, such as Git integration over SSH.

Using the API🔗

The Private key API endpoint is available at:

<InstanceAddress>/rest/v1/group/name/<groupName>/private-key

Where:

<InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
<groupName> is the name of the Project Group that the private key belongs to.

Note

Currently, create is the only operation available through this endpoint.

POST create🔗

Create and securely store a private key within a Project Group.

To create a private key, make the following POST call:

<InstanceAddress>/rest/v1/group/name/<groupName>/private-key/create

Where:

<InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
<groupName> is the name of the Project Group to create the private key in.

The POST body should contain the following, in JSON format:

{
    "name": "<privateKeyName>",
    "privateKey": "<privateKeyContent>",
    "passphrase": "<passphrase>",
    "description": "<description>",
    "encryptionType": "<encryptionType>"
}

<name> is a unique name for the private key within the group. Required.
<privateKey> is the private key content, in PEM format. Required.
<passphrase> is the passphrase used to decrypt the private key, if it's encrypted. Optional.
<description> is a description of the private key. Optional.
<encryptionType> is the type used to encode or encrypt the sensitive fields (privateKey and passphrase). Valid values are ENCODED, KMS, and KVS. Optional, and defaults to ENCODED.

A successful POST call to the endpoint returns a 201 Created response from the server, in JSON format:

{
    "message": "Private key created successfully",
    "privateKeyName": "<privateKeyName>",
    "group": "<groupName>"
}

If the call fails—for example, because of a duplicate name, an unsupported encryptionType, or invalid key material—the server returns a 400 Bad Request response, in JSON format:

{
    "error": "<error message>"
}

Creating a private key with KMS or KVS encryption🔗

If encryptionType is KMS, include a masterKey field containing the Amazon Resource Name (ARN) of the AWS KMS key to use:

{
    "name": "<privateKeyName>",
    "privateKey": "<privateKeyContent>",
    "passphrase": "<passphrase>",
    "description": "<description>",
    "encryptionType": "KMS",
    "masterKey": "<kmsKeyArn>"
}

If encryptionType is KVS, include an extraInfo object with the Azure Key Vault details to use:

{
    "name": "<privateKeyName>",
    "privateKey": "<privateKeyContent>",
    "description": "<description>",
    "encryptionType": "KVS",
    "extraInfo": {
        "resourceGroup": "<resourceGroup>",
        "keyVault": "<keyVault>",
        "key": "<key>",
        "algorithm": "<algorithm>"
    }
}

<resourceGroup> is the Azure resource group that contains the key vault.
<keyVault> is the name of the Azure key vault.
<key> is the name of the key within the key vault.
<algorithm> is the encryption algorithm to use, for example RSA_OAEP.