Authenticating to the API

This document provides essential information on setting up and authorizing API credentials for your Data Productivity Cloud account with the Matillion API.

Prerequisites

A Data Productivity Cloud account.
Valid API credentials.
Only users with the Super Admin role can create and view API credentials.

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

Note

Each account must have at least one user with the Super Admin role at all times. Removal or changes to a user with the Super Admin role must be done by another user with the Super Admin role.
Accounts created before December 2024 do not have a Super Admin user automatically assigned. If you wish to elevate an existing user to have the Super Admin role, raise a Support ticket. For more information, read Getting support.

API credentials

The Matillion API uses the following credentials:

Client ID: The unique public identifier associated with your Data Productivity Cloud account. This is automatically generated when you create the credentials 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 30 minutes. You can request a new token when one expires.

Create and configure API credentials

Step 1: Generate API credentials

Log in to the Data Productivity Cloud.
In the left navigation, click your Profile & Account icon. Then, select API credentials from the 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 an 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.

cURL 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

Note

Depending on your operating system, the cURL command uses a different line continuation character:

Windows (PowerShell), use ^.
macOS/Linux (bash/zsh), use \.

Step 3: Obtaining an API 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 cURL request:

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

Tokens have a limited lifespan; ensure to manage and refresh them accordingly.
Depending on your operating system, the curl command uses a different line continuation character:
- Windows (PowerShell), use `.
- macOS/Linux (bash/zsh), use \.

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 Data Productivity Cloud.
In the left navigation, click your Profile & Account icon. Then, select API credentials from the 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 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 Data Productivity Cloud 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.

Got feedback or spotted something we can improve?

We'd love to hear from you. Join the conversation in the Documentation forum!