Skip to content

API v1 - OAuth

This article is a guide to using the OAuth API in Matillion ETL. OAuth is used in conjunction with APIs to enable secure and controlled access to protected resources. The OAuth protocol defines how the API can grant access to third-party applications and services without exposing sensitive user credentials like usernames and passwords, and import data from service providers, such as Facebook, Salesforce, Hubspot, and Bing Ads. Matillion ETL abstracts the OAuth setup for all OAuth APIs to make this process as easy as possible.

Prerequisites

  • Users responsible for experimenting with Matillion ETL API services require access to the Matillion ETL instance and ought to 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.
  • If you are new to Matillion ETL's API, read our Matillion API introduction and explore the v1 API map.
  • 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.
  • Read Manage OAuth for information about how to add an OAuth in your Matillion ETL instance. It's recommended that you refer to the required "Authentication Guide" from Matillion's online documentation.

Using the API

Return OAuth information from a Matillion ETL instance by making a GET, POST or DELETE call with the form:

<InstanceAddress>/rest/v1/oauth/<endpoint>

Note

<InstanceAddress>/rest/v1/oauth is the base URI for all OAuth endpoints. Add the specific <endpoint> information for each function, documented in the below sections.

Where:

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

Get oauth

Returns a list of OAuths in this Matillion ETL instance.

To return a list of OAuths, make the following GET call:

<instanceAddress>/rest/v1/oauth

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

{
    "<oauthName>"   
}

Get properties

Returns the properties of the chosen OAuth.

To return the properties of the chosen OAuth, make the following GET call:

<InstanceAddress>/rest/v1/oauth/name/<oauthName>/properties

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

{
    "CallbackURL": "<OAuth Redirect URL>",
    "RefreshToken": "<Refresh Token>",
    "ClientSecret": "<Client Secret>",
    "AccessToken": "<Access Token>",
    "ClientID": "<Client ID>",
    "Verifier": "<OAuth Verifier>",
    "OrganizationUrl": "<OAuth Organization url>"
}

The response will include several properties, and will vary according to the selected OAuth.

Get id

Return the ID of the chosen OAUth.

To return the ID of the chosen OAuth, make the following GET call:

<InstanceAddress>/rest/v1/oauth/name/<oauthName>/id

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

{
    "<123456>"
}

Get name

Returns the name of the selected OAuth.

To return the name of the chosen OAuth, make the following GET call:

<InstanceAddress>/rest/v1/oauth/name/<oauthName>/name

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

{
    "<oauthName>"
}

Get type

Returns the "Type" of service mapped to your chosen OAuth.

To return the type of service of the chosen OAuth, make the following GET call:

<InstanceAddress>/rest/v1/oauth/name/<oauthName>/type

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

{
    "<service name>"
}

Get status

Returns the status of your chosen OAuth.

To return the status of the chosen OAuth, make the following GET call:

<InstanceAddress>/rest/v1/oauth/name/<oauthName>/status

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

{
    "<Configured>"
}

The status of your chosen OAuth response can be Configured or Not Configured.

Get settings

Returns the settings data of your chosen OAuth.

To return the settings of the chosen OAuth, make the following GET call:

<InstanceAddress>/rest/v1/oauth/name/<oauthName>/settings

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

{
    "success": true,
    "msg": "<xyz>",
    "id": -1
}

Get export

Export the selected OAuth details in this Matillion ETL instance.

To export the selected OAuth details of the chosen OAuth, make the following GET call:

<InstanceAddress>/rest/v1/oauth/name/<oauthName>/export

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

{
    "objects": [
        {
            "name": "<OAuthname>",
            "serviceID": "<ServiceID>",
            "properties": {
                "CallbackURL": "<OAuth Redirect URL>",
                "RefreshTokenValidFor": "0000000",
                "RefreshToken": "<Refresh Token>",
                "AccessToken": "<Access Token>",
                "ClientSecret": "<Client Secret>",
                "AccessTokenExpirationTime": "<DateTime of Expiration>",
                "ClientID": "<Client ID>",
                "AccessTokenValidFor": "0000"
            },
            "files": {},
            "type": "local"
        }
    ],
    "version": "Built",
    "environment": "environmentName"
}

The response will include several properties, and will vary according to the selected OAuth.

Post import

Import the details returned by GET Export. The "serviceID" is part of the Get export endpoint response, and is the unique identifier assigned to the OAuth by the server. You will need this value to return a successful response call for this endpoint.

Note

If a resource of the same name already exists, you must delete the existing resource before importing the new or you can change the name of the imported resource (OAuthImported) in the POST body.

To import the OAuth details of the chosen OAuth, make the following POST call:

<InstanceAddress>/rest/v1/oauth/import

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

{
    "objects": [
        {
            "name": "OAuthImported",
            "serviceID": "<serviceID>",
            "properties": {
                "CallbackURL": "<OAuth Redirect URL>",
                "RefreshToken": "<Refresh Token>",
                "ClientSecret": "<Client Secret>",
                "AccessToken": "<Access Token>",
                "ClientID": "<Client ID>",
                "Verifier": "<OAuth Verifier>",
                "OrganizationUrl": "<OAuth Organization url>"
            }
        },
    ]
}
  • name: The name of the OAuth you wanted to add into this Matillion ETL instance.
  • serviceID: Unique identifier assigned to the OAuth. Retrieve this value using the example in the GET/export endpoint.
  • CallbackURL: Send and receive the data after the authentication process, in this Matillion ETL instance.
  • RefreshToken: Obtain a renewed Access Token.
  • ClientSecret: A secret known only to Matillion ETL and the authentication server.
  • AccessToken: Normally used as an API Key. It allows Matillion ETL to access the user's data.
  • ClientID: A public identifier for the application.
  • Verifier: Verify access to the data of the user.
  • OrganizationUrl: The URL of the OAuth API user's platform.

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

{
    "name": "OAuths",
    "statusList": [
        {
          "success": true,
          "name": "OAuthImported"
        },
        ],
    "success": true
}

Post delete

Delete the selected OAuth from the collection of OAuths in this Matillion ETL instance.

To delete the selected OAuth, make the following POST call:

<InstanceAddress>/rest/v1/oauth/name/<oauthName>/delete

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

{
    "success": true,
    "msg": "Successfully deleted the OAuth with the name: OAuthName.",
    "id": 1
}

Delete oauth name

Delete the selected OAuth and its details from the Matillion ETL server.

To delete the selected OAuth, make the following DELETE call:

<InstanceAddress>/rest/v1/oauth/name/<oauthName>

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

{
    "success": true,
    "msg": "Successfully deleted the OAuth with the name: OAuthName.",
    "id": 1
}

Contact us

If any help is needed navigating the Oauth API in Matillion ETL, read Getting Support.