Skip to content

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.
  • Currently, only one pair of Client ID and Client Secret can be generated 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.

Steps to follow

Step 1: Generate API credentials

  1. Log in to the Hub.
  2. Click Manage on the left side of the window.
  3. Click API Credentials in the sub-menu.
  4. Click Set an API Credential to begin the process of creating a new Client ID and Client Secret.
  5. 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.
  6. Click Save to create the Client ID and Secret.
  7. 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.

You can remove a set of credentials by clicking the Delete button in the API Credentials sub-menu.

Step 2: Request for API Access Token

  1. Configure a POST request to the following URL:

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

  2. 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.

Get access token using Postman

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

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

Run In Postman

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