---
title: "OAuth1 authentication"
slug: "oauth1-authentication"
description: "Learn how to configure OAuth1 authentication, including request signing and token management, for seamless access to data sources like X."
updated: 2026-05-26T08:32:32Z
published: 2026-05-26T08:32:32Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `consumerKey` | string | Yes | Consumer key generated during app registration. **Values must be encrypted before inclusion.** |
| `consumerSecret` | string | Yes | Consumer secret generated during app registration. **Values must be encrypted before inclusion.** |
| `requestTokenEndpoint` | object | Yes | Configuration for the initial temporary token request. |
| `authorizationEndpoint` | object | Yes | Configuration for the user authorization redirect. |
| `accessTokenEndpoint` | object | Yes | Configuration for exchanging the request token for an access token. |

### requestTokenEndpoint

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `request.type` | string | Yes | Request type. Use `"sync"` for synchronous requests. |
| `request.url` | string | Yes | URL to the data source's request token endpoint. |
| `request.method` | string | Yes | HTTP method. Typically `"POST"`. |

### authorizationEndpoint

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `request.url` | string | Yes | URL where the user is redirected to grant authorization. |

### accessTokenEndpoint

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `request.url` | string | Yes | URL to exchange the authorized request token for an access token. |

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `request.method` | string | Yes | HTTP method for the validation request. Typically `"GET"`. |
| `request.url` | string | Yes | URL to a data source endpoint that confirms valid credentials. |
| `request.builderType` | string | Yes | Signing type for the request (e.g., `"twitter_signed"`). |
| `request.config.cache.useCache` | boolean | No | Whether to cache validation responses. Set to `false` to ensure fresh validation. |
| `request.response` | object | Yes | Response parsing configuration, including `type` and `dataRows`. |

## Available Placeholders

The following placeholders are available within the OAuth1 authentication flow:

| Placeholder | Type | Description |
| --- | --- | --- |
| `{{oauth1.consumer_key}}` | string | OAuth1 consumer key |
| `{{oauth1.consumer_secret}}` | string | OAuth1 consumer secret |
| `{{oauth1.callback_url}}` | string | OAuth1 callback URL |

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. For APIs that require custom cryptographic signatures beyond built-in OAuth1 signing, see [Request signers](https://docs.supermetrics.com/docs/request-signers)