OAuth1 authentication

OAuth1 is a legacy authorization protocol still used by some data sources, most notably X (formerly Twitter). Unlike OAuth2, OAuth1 requires cryptographic request signing and involves a three-legged flow to obtain access tokens.

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

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 OAuth1 signing and token management 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": "[encrypted consumer key]",
      "consumerSecret": "[encrypted consumer secret]",
      "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]"
        }
      }
    },
    "validation": {
      "request": {
        "method": "GET",
        "url": "[URL to a validation endpoint]",
        "builderType": "[signing type]",
        "config": {
          "cache": {
            "useCache": false
          }
        },
        "headers": [],
        "parameters": [],
        "response": {
          "type": "JSON",
          "dataRows": {
            "source": "jsonPath",
            "value": "[JSONPath to response data]"
          }
        }
      }
    }
  }
}

Configuration Fields

oauth1

requestTokenEndpoint

authorizationEndpoint

accessTokenEndpoint

validation

The validation object defines a request used to verify that the authentication credentials are valid. This request is executed after the user completes the OAuth1 flow.

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: X (Twitter) Organic

Below you can find a complete OAuth1 configuration example using the X (formerly Twitter) Organic connector:

{
  "authentication": {
    "type": "oauth1",
    "description": "This is an example OAuth1 Authentication configuration",
    "oauth1": {
      "consumerKey": "[encrypted consumer key]",
      "consumerSecret": "[encrypted consumer secret]",
      "requestTokenEndpoint": {
        "request": {
          "type": "sync",
          "url": "https://api.x.com/oauth/request_token",
          "method": "POST"
        }
      },
      "authorizationEndpoint": {
        "request": {
          "url": "https://api.x.com/oauth/authorize"
        }
      },
      "accessTokenEndpoint": {
        "request": {
          "url": "https://api.x.com/oauth/access_token"
        }
      }
    },
    "validation": {
      "request": {
        "method": "GET",
        "url": "https://ads-api.x.com/12/accounts",
        "builderType": "twitter_signed",
        "config": {
          "cache": {
            "useCache": false
          }
        },
        "headers": [],
        "parameters": [],
        "response": {
          "type": "JSON",
          "dataRows": {
            "source": "jsonPath",
            "value": "$.data.*"
          }
        }
      }
    }
  }
}

Data Source User Configuration

After OAuth1 authentication, you can fetch user identity information to store with the connection. Below you can find the corresponding dataSourceUser configuration from the X connector:

{
  "dataSourceUser": {
    "request": {
      "url": "https://api.x.com/1.1/account/verify_credentials.json",
      "builderType": "twitter_signed",
      "type": "sync",
      "method": "GET",
      "response": {
        "type": "JSON",
        "dataRows": {
          "source": "jsonPath",
          "value": "$"
        }
      }
    },
    "userInfo": {
      "id": {
        "source": "jsonPath",
        "value": "$.id_str"
      },
      "label": {
        "source": "jsonPath",
        "value": "$.name"
      }
    }
  }
}

Using OAuth1 Credentials in Requests

For data sources using OAuth1, requests must be signed. Set the builderType field on your requests to the appropriate signing type. For X (Twitter), use "twitter_signed":

{
  "request": {
    "url": "https://ads-api.x.com/12/accounts/{{account.id}}/tweets",
    "builderType": "twitter_signed",
    "method": "GET",
    "parameters": [
      {
        "name": "tweet_type",
        "value": "PUBLISHED"
      }
    ],
    "response": {
      "type": "JSON",
      "dataRows": {
        "source": "jsonPath",
        "value": "$.data.*"
      }
    }
  }
}

Note: Unlike OAuth2 where you manually include Bearer {{user.access_token}} in headers, OAuth1 request signing is handled automatically by the platform when you specify the correct builderType. You do not need to add authorization headers manually.