OAuth1 authentication

OAuth1 is a legacy authorization protocol still used by some data sources. Unlike OAuth2, OAuth1 signs each request to the data source rather than sending a bearer token, and it involves a three-legged flow to obtain access tokens.

To configure OAuth1 authentication, add an authentication component with type: "oauth1" to your connector configuration.

Prerequisites for configuring OAuth1 authentication

Before configuring OAuth1 authentication, you need to:

• Register an application with the data source platform. This gives you the consumer key and consumer secret your connector uses to identify itself.
• Know the data source's OAuth1 endpoints — the request token, authorization, and access token URLs.

When registering the application, the data source usually asks you to configure a callback URL, so it knows where to send the user after successful authentication. The callback URL used by Supermetrics is always https://supermetrics.com/login-complete, and it is available in the configuration through the {{oauth1.callback_url}} placeholder.

Authentication Flow

The OAuth1 authentication process consists of three stages:

1. Request token — Your connector obtains a temporary request token from the data source API.
2. User authorization — The user is redirected to the data source to grant permission.
3. Access token exchange — The temporary token is exchanged for a permanent access token after the user authorizes access.

Supermetrics handles the signing and token management for these three authentication steps automatically. You only need to provide the endpoint URLs and your consumer credentials.

Configuration Template

Below you can find a template for OAuth1 authentication configuration:

{
  "authentication": {
    "type": "oauth1",
    "description": "[Description shown to users during the authentication flow]",
    "oauth1": {
      "consumerKey": {
        "source": "secret",
        "value": "[secret ID]"
      },
      "consumerSecret": {
        "source": "secret",
        "value": "[secret ID]"
      },
      "requestTokenEndpoint": {
        "request": {
          "type": "sync",
          "url": "[URL to request token endpoint]",
          "method": "POST"
        }
      },
      "authorizationEndpoint": {
        "request": {
          "url": "[URL to authorization endpoint]"
        }
      },
      "accessTokenEndpoint": {
        "request": {
          "url": "[URL to access token endpoint]"
        }
      }
    }
  }
}

The consumerKey and consumerSecret are registered as secrets and set through the source: "secret" value source, which is the recommended way to keep sensitive credentials out of plain-text configuration. See Consumer credentials below for how to register them.

Consumer credentials

The consumerKey and consumerSecret are the credentials generated when you register your application with the data source. These are sensitive, fixed, application-wide values, so rather than storing them directly in the configuration we register them as secrets. Using secrets keeps the values out of plain-text configuration and is the recommended, most secure way to handle credentials in the Connector builder.

Encrypt each value once using the secret encryption tool in the Connector builder. When you encrypt a value, it is stored in the Connector builder vault and the matching entry in the secrets object is created for you automatically, resolving the value from the vault:

{
  "secrets": {
    "items": [
      {
        "id": "sec_consumer_key",
        "classification": "secret",
        "component": {
          "override": {
            "componentId": "connector_builder_vault"
          }
        },
        "value": "sec_consumer_key"
      },
      {
        "id": "sec_consumer_secret",
        "classification": "secret",
        "component": {
          "override": {
            "componentId": "connector_builder_vault"
          }
        },
        "value": "sec_consumer_secret"
      }
    ]
  }
}

Then point the consumerKey and consumerSecret properties of the oauth1 object at these secrets using the source: "secret" value source, with value set to the secret's id:

"oauth1": {
  "consumerKey": {
    "source": "secret",
    "value": "sec_consumer_key"
  },
  "consumerSecret": {
    "source": "secret",
    "value": "sec_consumer_secret"
  },
  ...
}

Signing OAuth1 requests

OAuth1 signs each request to the data source rather than attaching a bearer token. Supermetrics signs the three authentication-flow steps (request token, authorization, access token) for you automatically. The other requests your connector makes — such as account fetching and reporting — are signed through the connector's request signing capability: you define a signer once and reference it from the requests that need it, rather than adding authorization headers by hand.

For how to define a signature and attach it to your requests, see Request signers.

Note: After authentication completes, the user's access token is available as {{user.access_token}} for use in your signing configuration.

Configuration Fields

oauth1

requestTokenEndpoint

authorizationEndpoint

accessTokenEndpoint

Available Placeholders

The following placeholders are available within the OAuth1 authentication flow:

After authentication completes, the user's access token is available as {{user.access_token}} in subsequent requests (data source user, account fetching, reporting, etc.).

Complete Example: Trello

Below you can find a complete OAuth1 configuration example using the Trello API, which uses OAuth1 for authentication:

{
  "authentication": {
    "type": "oauth1",
    "description": "This is an example OAuth1 Authentication configuration",
    "oauth1": {
      "consumerKey": {
        "source": "secret",
        "value": "sec_consumer_key"
      },
      "consumerSecret": {
        "source": "secret",
        "value": "sec_consumer_secret"
      },
      "requestTokenEndpoint": {
        "request": {
          "type": "sync",
          "url": "https://trello.com/1/OAuthGetRequestToken",
          "method": "POST"
        }
      },
      "authorizationEndpoint": {
        "request": {
          "url": "https://trello.com/1/OAuthAuthorizeToken"
        }
      },
      "accessTokenEndpoint": {
        "request": {
          "url": "https://trello.com/1/OAuthGetAccessToken"
        }
      }
    }
  },
  "secrets": {
    "items": [
      {
        "id": "sec_consumer_key",
        "classification": "secret",
        "component": {
          "override": {
            "componentId": "connector_builder_vault"
          }
        },
        "value": "sec_consumer_key"
      },
      {
        "id": "sec_consumer_secret",
        "classification": "secret",
        "component": {
          "override": {
            "componentId": "connector_builder_vault"
          }
        },
        "value": "sec_consumer_secret"
      }
    ]
  }
}

Data Source User Configuration

After OAuth1 authentication, you can fetch user identity information to store with the connection. Below you can find a corresponding dataSourceUser configuration for the Trello example, using the members/me endpoint. Like any OAuth1 data request, it references a signer so the request is signed — define the signer and replace [signer ID] with its id, as described in Request signers:

{
  "dataSourceUser": {
    "request": {
      "url": "https://api.trello.com/1/members/me",
      "type": "sync",
      "method": "GET",
      "signer": {
        "id": "[signer ID]"
      },
      "response": {
        "type": "JSON",
        "dataRows": {
          "source": "jsonPath",
          "value": "$"
        }
      }
    },
    "userInfo": {
      "id": {
        "source": "jsonPath",
        "value": "$.id"
      },
      "label": {
        "source": "jsonPath",
        "value": "$.fullName"
      }
    }
  }
}