Skip to content

Authentication

You can create and store OAuth connections across the Data Productivity Cloud to authenticate data sources. OAuth connections are used to securely authenticate and authorize access to external services or APIs that you want to integrate with in your Matillion workflows.

Any existing OAuth entries are listed on this page, oldest first. Click the trashcan button alongside an OAuth entry to delete it, and then click Yes, delete to confirm deletion or click Never mind to cancel the deletion process.

Add an OAuth entry

The Add new OAuth modal requires your app's credentials. You'll need to know these credentials, or have access to the app. Contact your administrator for your data source service if you don't have the required permissions.

To add a new OAuth entry:

  1. Click Add OAuth.

  2. In the Add new OAuth modal, complete the following fields:

    Property Description
    Name A unique, descriptive name for the OAuth entry.
    Grant Type Select a grant type. Choose either Authorization Code or Client Credentials. The appropriate choice depends on the authentication flow supported by your data source service. Read Which should I use? for guidance.
    Credentials Mechanism If the selected grant type is Authorization Code, choose whether the credentials should be formatted in the request body or as request headers when initially requesting an access token.
    Client ID A unique client ID string for your application. This credential will be available when you create an app for your data source service in the corresponding developer portal.
    Client Secret A unique client secret string for your application. This credential is usually available when you create an app for your data source service in the developer portal. Note that some services only reveal the client secret once during app creation, so it's important to securely copy and save it for future access.
    Authorize URL If the grant type is Authorization Code, provide the authorization URL of your app.
    Access Token URL Enter the URL that provides an API access token for your app.

  3. Click Authorize to create the OAuth connection, attempting to authorize and obtain an access token. For the Authorization Code grant type, you will be redirected to the third-party service's authorization page, where you will grant permission for Matillion to access your data. After confirmation, the third-party service will redirect you back to the Data Productivity Cloud.

Any errors that occur during the authorization attempt will be displayed at this step, with error details.

Which Grant Type should I use?

The grant type options available when adding an OAuth entry represent the two main types of flow for OAuth. Here's a breakdown of the two main grant types:

  • Authorization Code: the details you enter are used to redirect you to the third-party service where you'll grant Matillion Custom Connector access to your data. The Authorization Code flow typically involves the following steps:
    • You are redirected to the third-party service's authorization page.
    • You authenticate and authorize Matillion to access your data.
    • After confirmation, the third-party service redirects you back to the Matillion Platform with an authorization code.
    • Matillion exchanges the authorization code for an access token, which is used to authenticate future requests.
  • Client Credentials: the details you enter are all that's needed to authenticate on an ongoing basis. The Client Credentials flow typically involves the following steps:
    • Matillion directly exchanges the provided client ID and client secret for an access token.
    • The access token is used to authenticate requests made by Matillion Custom Connector.

The Authorization Code flow is commonly used when the third-party service requires explicit user consent or when accessing user-specific data. If the third-party API documentation mentions an authorization URL, scopes, or asks for a callback URL, it's likely that you should choose the Authorization Code Grant Type.

The Client Credentials flow is recommended where possible because it offers a more straightforward integration and fewer potential issues. However, not all APIs support this flow, and some may only provide the Authorization Code flow. If your third-party service does not require explicit user consent and only needs application-level access, you can choose the Client Credentials Grant Type.

If you're not sure which option to choose, check the details and documentation provided by your third-party service. If they show a URL that includes authorize, discusses scopes, or asks you for a callback URL, then it's the Authorization Code flow.