--- title: "OAuth2 authentication in Connector builder | Supermetrics" slug: "oauth2-authentication" description: "Learn how to configure OAuth2 authentication for the Connector Builder for seamless app interactions, including token exchange and refresh." updated: 2026-10-19T12:01:32Z published: 2026-10-19T12:01:32Z canonical: "docs.supermetrics.com/oauth2-authentication" --- > ## 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. # OAuth2 authentication OAuth2 is the industry-standard protocol for authorization. It allows different applications to interact with each other on behalf of the user without the user giving out their credentials. ## Prerequisites for configuring OAuth2 authentication The OAuth2 authentication requires you to create a developer application on the data source platform, and you can then use the Client ID and Client Secret provided by the platform in your configuration. When creating the application, it usually requires you to configure a callback URL, so the data source platform knows where to send the user after successful authentication. The callback URL used by Supermetrics is always `https://supermetrics.com/login-complete`. ## OAuth2 authentication flow OAuth2 authentication flow consists of a few distinct steps that we will need to configure: - `authorization`: The initial request to send an authorization request to the data source API - `tokenExchange`: Request to exchange authorization code for an actual access token, as well as to receive a refresh token. - Access tokens usually have a relatively short lifetime, but they can be programmatically refreshed using a refresh token. - `refresh`: Request to fetch a new token before the old one expires. ## Template OAuth2 configuration Below you can find a template configuration that you can fill in with your own information for an easier start. The Client ID and Client Secret are registered as [secrets](https://docs.supermetrics.com/docs/secrets) and set on the `oauth2` object through the `source: "secret"` value source, which is the recommended way to keep sensitive credentials out of plain-text configuration. Once set this way, the rest of the flow uses `{{oauth2.client_id}}` and `{{oauth2.client_secret}}` placeholders: ``` { "authentication": { "type": "oauth2", "description": "Example description shown to users in the authentication screen.", "oauth2": { "clientId": { "source": "secret", "value": "[secret ID]" }, "clientSecret": { "source": "secret", "value": "[secret ID]" }, "tokenLifetime": 3600, "tokenJsonPath": "$[path to access token in JSON response]", "authorization": { "request": { "url": "[url to authorization endpoint]", "parameters": [ { "name": "[parameter name]", "value": "[parameter value]" } ] } }, "tokenExchange": { "request": { "method": "POST", "url": "[url to token exchange endpoint]", "body": { "type": "urlencoded_form", "formData": [ { "name": "grant_type", "value": "authorization_code" }, { "name": "code", "value": "{{oauth2.code}}" }, { "name": "client_id", "value": "{{oauth2.client_id}}" }, { "name": "client_secret", "value": "{{oauth2.client_secret}}" }, { "name": "redirect_uri", "value": "{{oauth2.callback_url}}" } ] } } }, "refresh": { "request": { "method": "POST", "url": "[url to token refresh endpoint]", "body": { "type": "urlencoded_form", "formData": [ { "name": "grant_type", "value": "refresh_token" }, { "name": "refresh_token", "value": "{{oauth2.refresh_token}}" }, { "name": "client_id", "value": "{{oauth2.client_id}}" }, { "name": "client_secret", "value": "{{oauth2.client_secret}}" } ] } } } } } } ``` > **Note:** The `clientId` and `clientSecret` reference secrets by their `id` (`[secret ID]` above). You don't need to add the `secrets` entries themselves – they're created in the configuration for you automatically when you encrypt the Client ID and Client Secret with the secret encryption tool and store them in the vault. See [Client ID and Client Secret](/docs/oauth2-authentication#client-id-and-client-secret) below. ## Configuring OAuth2 authentication We'll instruct you to configure OAuth2 authentication flow using Spotify Ads API as an example. The authentication details for the Spotify Ads API can be found here: - [Ads API Quickstart | Spotify for Developers](https://developer.spotify.com/documentation/ads-api/quick-start#set-up-your-ad-studio-api-application) - [Authorization | Spotify for Developers](https://developer.spotify.com/documentation/web-api/concepts/authorization) To configure OAuth2 authentication to Spotify Ads, we need to: 1. Add `authentication` component with type `oauth2`. 2. Register Client ID and Client Secret as secrets. 3. Configure the Authentication endpoint and request under the `authorization` object. 4. Define the JSON path to get the token in the response and define the lifetime for the token. 5. Token exchange under `tokenExchange` object. 6. Token refresh under `tokenRefresh` object. ### Base configuration for OAuth2 authentication Let's start by defining the base configuration for OAuth2 authentication type: ``` "authentication": { "type": "oauth2", "description": "Description shown to users during the authentication flow", "oauth2": { ... } } ``` ### Client ID and Client Secret First, we need to provide the Client ID and Client Secret for the app that we've registered on the data source platform. These are sensitive application credentials, so rather than storing them directly in the configuration we register them as [secrets](https://docs.supermetrics.com/docs/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. Because the Client ID and Client Secret are fixed, application-wide values that are the same for every user, we encrypt them once using the **secret encryption tool** in the Connector builder. When you encrypt a value with the tool, 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_client_id", "classification": "secret", "component": { "override": { "componentId": "connector_builder_vault" } }, "value": "sec_client_id" }, { "id": "sec_client_secret", "classification": "secret", "component": { "override": { "componentId": "connector_builder_vault" } }, "value": "sec_client_secret" } ] } ``` We then point the `clientId` and `clientSecret` properties of the `oauth2` object at these secrets using the `source: "secret"` value source, with `value` set to the secret's `id`: ``` "authentication": { "type": "oauth2", "description": "Description shown to users during the authentication flow", "oauth2": { "clientId": { "source": "secret", "value": "sec_client_id" }, "clientSecret": { "source": "secret", "value": "sec_client_secret" }, ... } } ``` With the credentials set on the `oauth2` object this way, the rest of the authentication flow continues to reference them with the `{{oauth2.client_id}}` and `{{oauth2.client_secret}}` placeholders – the values now resolve from the secrets behind the scenes. ### Authorization Next, we'll configure the `authorization` object under the `oauth2` object to define how the first authentication request is done. You can see the documentation on how Spotify Ads API requires the authentication request to be made in Spotify's documentation: [Authenticate your Ads Manager account](https://developer.spotify.com/documentation/ads-api/quick-start#authenticate-your-ad-studio-account) The authentication request is done by adding the `request` object with the required `url` and `parameters`. You'll need to match the URL and parameters to the API you're working with, which in this case are the following: - client_id - response_type - redirect_uri - state (This is a parameter required by Supermetrics and provides protection against attacks such as cross-site request forgery (see [RFC-6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1))) The request `url` is configured as a string, and the `parameters` as an array, like in the example below. For most of the values, we want to use ready placeholders to ensure the values will always be correct. The configuration would look like this: ``` "authorization": { "request": { "url": "https://accounts.spotify.com/authorize/", "parameters": [ { "name": "client_id", "value": "{{oauth2.client_id}}" }, { "name": "response_type", "value": "code" }, { "name": "redirect_uri", "value": "{{oauth2.callback_url}}" }, { "name": "state", "value": "{{oauth2.state}}" } ] } } ``` ### Token exchange Next, we need to configure how the authorization code received after user authorization is exchanged to the access token. This can be done in the Spotify Ads API by making a POST request to the endpoint `https://accounts.spotify.com/api/token` with the following details: - Base64 encoded client ID and client secret as `Authorization` header. - Request body with following parameters: - `grant_type` with string value `authorization_code` - `code` with the code received from the previous request - `redirect_uri` with the callback URL of Supermetrics This is configured as `request` object under `tokenExchange` object, and we will use placeholders for most of the values, and [placeholder operations](https://docs.supermetrics.com/v1/docs/placeholders#placeholder-operations) to have client ID and secret encoded with Base64 encoding. The configuration will look like this: ``` "tokenExchange": { "request": { "url": "https://accounts.spotify.com/api/token", "method": "POST", "headers": [ { "name": "Authorization", "value": "{{base64(oauth2.client_id, ':', oauth2.client_secret)}}" } ], "body": { "type": "urlencoded_form", "formData": [ { "name": "grant_type", "value": "authorization_code" }, { "name": "code", "value": "{{oauth2.code}}" }, { "name": "redirect_uri", "value": "{{oauth2.callback_url}}" } ] } } } ``` ### Token JSONpath and Token lifetime Next, we will configure JSONpath to find the token from the response and the lifetime for the token. After calling the Spotify Ads API to authenticate, the response will look like this: ![Image](https://cdn.document360.io/a13cead5-eaae-456f-9bd1-0941d590c0e3/Images/Documentation/a785aecb-bd3c-431f-bd21-023717dfbbc2(1).png) We can see that the access token is provided in the parameter `access_token`, refresh token in `refresh_token`, and the lifetime of the token is 3600 seconds. To find the access token, to know when to refresh it, and what refresh token to use, we need to configure the `tokenJsonPath` and `tokenLifeTime` properties under the `oauth2` object and the `refreshTokenJsonPath` property under the `tokenExchange` object in the connector configuration. - `tokenJsonPath` is configured as a string with JSONpath to the field `access_token` in the response. - `tokenLifeTime` is configured as an integer with the number of seconds how long the token is valid. - Note: Token lifetime can also be defined to be read dynamically from the response using `expiresInJsonPath` property - `refreshTokenJsonPath` is configured as a string with JSONpath to the field `refresh_token` in the response. - Note: While the other configuration comes directly under `oauth2` object, the refresh token configuration should be done under `tokenExchange`. The configuration will look like this: ``` { "authentication": { "type": "oauth2", "description": "Description shown to users during the authentication flow", "oauth2": { "clientId": { "source": "secret", "value": "sec_client_id" }, "clientSecret": { "source": "secret", "value": "sec_client_secret" }, "authorization": { "request": { ... } }, "tokenExchange": { "request": { ... }, "refreshTokenJsonPath": "$.refresh_token" }, "tokenJsonPath": "$.access_token", "tokenLifetime": 3600 } } } ``` Now you should already have a finalized authentication where you have received the actual access token from the API, which you can already start using in reporting requests! However, this access token is set to expire after a short time by the API, so we want to next configure the token refresh flow to ensure the token is automatically refreshed by our system. ### Token refresh Access tokens granted by OAuth2 flow are commonly set to expire after short time. In Spotify Ads API, the lifetime of the token is 3600 seconds which is 60 minutes. In order to ensure you don't need to authenticate again after every 60 minutes, we want to configure an automatic token refresh flow. This is done by configuring the `tokenRefresh` object under the `oauth2` configuration. Under `tokenRefresh`, we can define a request to be made to refresh the token. The Spotify Ads API requires a POST request to the endpoint `https://accounts.spotify.com/api/token` with the following details: - Base64 encoded client ID and client secret as `Authorization` header. - Request body with following parameters: - `grant_type` with string value `refresh_token` - `refresh_token` with the refresh token received from the authentication step The configuration for refresh token will look like this: ``` "refresh": { "request": { "url": "https://accounts.spotify.com/api/token", "method": "POST", "headers": [ { "name": "Authorization", "value": "{{base64(oauth2.client_id, ':', oauth2.client_secret)}}" } ], "body": { "type": "urlencoded_form", "formData": [ { "name": "grant_type", "value": "refresh_token" }, { "name": "refresh_token", "value": "{{oauth2.refresh_token}}" } ] } } } ``` Now you should have all the necessary configurations for a successful OAuth2 authentication! Here you can see the full configuration for all the steps defined above: ``` { "authentication": { "type": "oauth2", "description": "Description shown to users during the authentication flow", "oauth2": { "clientId": { "source": "secret", "value": "sec_client_id" }, "clientSecret": { "source": "secret", "value": "sec_client_secret" }, "authorization": { "request": { "url": "https://accounts.spotify.com/authorize/", "parameters": [ { "name": "client_id", "value": "{{oauth2.client_id}}" }, { "name": "response_type", "value": "code" }, { "name": "redirect_uri", "value": "{{oauth2.callback_url}}" }, { "name": "state", "value": "{{oauth2.state}}" } ] } }, "tokenExchange": { "request": { "url": "https://accounts.spotify.com/api/token", "method": "POST", "headers": [ { "name": "Authorization", "value": "{{base64(oauth2.client_id, ':', oauth2.client_secret)}}" } ], "body": { "type": "urlencoded_form", "formData": [ { "name": "grant_type", "value": "authorization_code" }, { "name": "code", "value": "{{oauth2.code}}" }, { "name": "redirect_uri", "value": "{{oauth2.callback_url}}" } ] } }, "refreshTokenJsonPath": "$.refresh_token" }, "tokenJsonPath": "$.access_token", "tokenLifetime": 3600, "refresh": { "request": { "url": "https://accounts.spotify.com/api/token", "method": "POST", "headers": [ { "name": "Authorization", "value": "{{base64(oauth2.client_id, ':', oauth2.client_secret)}}" } ], "body": { "type": "urlencoded_form", "formData": [ { "name": "grant_type", "value": "refresh_token" }, { "name": "refresh_token", "value": "{{oauth2.refresh_token}}" } ] } } } } }, "secrets": { "items": [ { "id": "sec_client_id", "classification": "secret", "component": { "override": { "componentId": "connector_builder_vault" } }, "value": "sec_client_id" }, { "id": "sec_client_secret", "classification": "secret", "component": { "override": { "componentId": "connector_builder_vault" } }, "value": "sec_client_secret" } ] } } ``` ### Using OAuth2 token in requests Now that you have configured a successful OAuth2 flow, you can start using the OAuth2 access token in other requests. For this, we'll be using placeholders, so we ensure all the requests will always use the latest refreshed token. The token can be used in the request object using a placeholder `{{user.access_token}}` in anywhere in the configuration: in account fetching, reporting, and so on. The configuration for it will usually look like this: ``` ... "request": { "url": "http://...", "headers": [ { "name": "Authorization", "value": "Bearer {{user.access_token}}" } ], ... } ```