Authenticating to the API

This document provides essential information on setting up and authorizing API credentials for your Hub account with Matillion's API.

Prerequisites

Both a Hub account and valid API credentials are essential for accessing Matillion's API.
Only admin users have the privilege to create API credentials.

Note

Currently, you can only have one pair of Client ID and Client Secret credentials per account.

Matillion's API credentials

Matillion's API utilizes the following credentials:

Client ID: The unique public identifier associated with your Hub account. This is automatically generated by your Hub account and is visible for the lifetime of the credentials.
Client Secret: The unique password required to access the API. This is not visible after it has been generated.
API Token: You will need to request an API token using your Client ID and Client Secret as part of the authentication process, which is detailed later. An API token is valid for 2 hours. You can request a new token when one expires.

Create and configure API credentials

Step 1: Generate API credentials

Log in to the Hub.
Click Manage on the left side of the window.
Click API Credentials in the sub-menu.
Click Set an API Credential to begin the process of creating your Client ID and Client Secret.

Note

If you already have a set of credentials for your account, you will need to delete the existing credentials before you can create a new set. To do this, read Delete existing API credentials below.
Give your credential set a descriptive Name. We recommend that you use a name that suits the application or purpose the credentials will be used for.
Click Save to create the Client ID and Secret.
Copy the secret immediately. You are not able to view the secret again after this point. If you do not copy it, or otherwise lose it, you will need to delete these credentials and generate a new set. The Secret window will close automatically after this point.

Step 2: Request for API Access Token

Configure a POST request to the following URL:

https://id.core.matillion.com/oauth/dpc/token

Include the following snippet in the request body. You will require the Client ID and Client Secret you created earlier.

curl --location 'https://id.core.matillion.com/oauth/dpc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'audience=https://api.matillion.com'

Replace <CLIENT_ID> and <CLIENT_SECRET> with the corresponding values.

Windows command for getting a token:

curl -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=<YOUR_CLIENT_ID>8&client_secret=<YOUR_CLIENT_SECRET>" \
     -X POST https://id.core.matillion.com/oauth/dpc/token

Step 3: Obtaining the access token

The response will be a JSON object containing the access token. Note that this token will expire after 30 minutes.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJYTzUtTWtvM0hPYWtJRkdIeXNCSFp2RnQ5SElYRzcxWmhudlJjVnc4UEtvIn0...",
  "expires_in": 1800,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "pipeline-execution"
}

Step 4: Making the request

Use the obtained access token to make requests to the API. Example request to get the list of projects:

curl --location 'https://eu1.api.matillion.com/dpc/v1/projects?page=0&size=25' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Replace <ACCESS_TOKEN> with the actual value of the access token.

Example request in Windows

curl -X GET "https://us1.api.matillion.com/dpc/v1/projects" `
     -H "Content-Type: application/x-www-form-urlencoded" `
     -H "Authorization: Bearer <example_bearer_token>" `
     -d "page=0&size=25"

Note

The access token is essential for making authorized requests.
Tokens have a limited lifespan; ensure to manage and refresh them accordingly.

Delete existing API credentials

You can only have one set of API credentials per account. To delete your existing API credentials, follow these steps:

Log in to the Hub.
Click Manage on the left side of the window.
Click API Credentials in the sub-menu.
In the credentials row, click the Delete icon.
In the Delete API Credential dialog, click Delete.

Warning

Deleted API credentials cannot be recovered or restored. Deleting API credentials may break any integrations with API consumers that use these credentials.

Get access token using Postman

Retrieve your access token by testing and interacting with the Matillion API collection using Postman. Follow these simple steps:

Click the Run in Postman button provided below.
In your Postman dashboard, navigate and select the Post access token endpoint. This section comes pre-filled with parameters and headers.
In the Body section, provide your Hub account's client ID and client secret.
Click Send, and your access token is ready for use.

To use access tokens for authenticating API endpoints and testing an endpoint, refer to the API reference user guide.