Universal OAuth Connection Guide

Universal OAuth is a flexible authentication service that allows you to connect to any OAuth-based API. This guide explains the three authentication methods available and how to use them with REST API components.

Overview

When working with modern APIs, most services require authentication to access their data. Universal OAuth supports three authentication methods:

• OAuth 2.0 - The standard authorization flow where you log in through the provider's website
• Client Credentials - Server-to-server authentication using API keys
• Custom Auth - Flexible option for non-standard authentication endpoints

Once authenticated, your connection can be used in REST API Source and Destination components to read from or write to any API.

OAuth 2.0 (Authorization Code Flow)

This is the most common authentication method used by services like Google, GitHub, Slack, Salesforce, and many others. It provides secure access without sharing your password with third-party applications.

How It Works

1. Configure your connection - Enter your Client ID, Client Secret, and the provider's OAuth URLs
2. Click "Authenticate" - A popup window opens showing the provider's login page
3. Log in and authorize - Sign in to your account and grant permission to access your data
4. Connection is established - The popup closes and your connection is ready to use

Configuration Fields

Security Features

Universal OAuth implements industry-standard security measures:

• PKCE (Proof Key for Code Exchange) - Prevents authorization code interception attacks
• State Parameter - Protects against cross-site request forgery (CSRF) attacks
• Automatic Token Refresh - Tokens are automatically refreshed before they expire (when refresh tokens are available)

Client Credentials

Client Credentials authentication is designed for server-to-server communication where no user interaction is required. This is commonly used for backend services, automated processes, and APIs that don't access user-specific data.

How It Works

1. Enter your credentials - Provide your Client ID and Client Secret
2. Click "Authenticate" - The system directly requests an access token from the provider
3. Token is received - No popup or user login required

Configuration Fields

Advanced Options

• Use HTTP Basic Authentication - Send credentials in the Authorization header instead of the request body (required by some providers)
• Use custom parameter key names - Some APIs use non-standard parameter names for client credentials

When to Use Client Credentials

• Accessing APIs that don't require user authorization
• Machine-to-machine communication
• Background jobs and automated processes
• APIs that use API keys or service accounts

Custom Auth

Custom Auth provides maximum flexibility for APIs that don't follow standard OAuth patterns. You can configure any HTTP request to obtain an access token from any endpoint.

How It Works

1. Configure the request - Specify the HTTP method, URL, headers, and body
2. Define the token path - Tell the system where to find the access token in the response
3. Click "Authenticate" - The system makes the configured request and extracts the token

Configuration Fields

Understanding Response Path (JSONPath)

The Response Path tells the system where to find the access token in the API's response. Use dot notation to navigate nested JSON structures:

{
  "status": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600
  }
}

Path Examples

When to Use Custom Auth

• APIs with non-standard authentication endpoints
• Legacy APIs that don't follow OAuth 2.0
• APIs requiring custom headers or body parameters
• Token endpoints that return tokens in non-standard response formats

Custom Authentication Header

By default, the access token obtained from any authentication flow (OAuth 2.0, Client Credentials, or Custom Auth) is sent as a Bearer token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Some APIs require the token to be sent using a different header name or format. For example, Shopify uses X-Shopify-Access-Token instead of Authorization: Bearer. The "Use custom authentication header" checkbox allows you to customize how the token is sent.

How to Configure

1. Check the "Use custom authentication header" checkbox (available on all three OAuth types)
2. Enter the Header Name - the HTTP header to use for authentication
3. Optionally enter a Header Prefix - the text placed before the token value. Leave empty to send the token without any prefix.

Configuration Fields

Examples

Using Your Connection in REST API Components

Once you've created a Universal OAuth connection, you can use it in REST API Source and Destination components to authenticate your API requests.

How Authentication Works

When you select a Universal OAuth connection in a REST API component:

1. The system retrieves the stored access token from your connection
2. The token is automatically added to your API requests using the configured authentication header (default: Authorization: Bearer {token})
3. If a custom authentication header is configured, the token is sent using the specified header name and prefix instead
4. Your request is sent to the API with proper authentication

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

X-Shopify-Access-Token: shpua_ff47f0800268bf212f8...

Setting Up a REST API Source

1. Add a REST API Source component to your pipeline
2. In the Choose input connection section, select Connection
3. Choose your Universal OAuth connection from the dropdown
4. Configure your API endpoint URL and other settings
5. The authentication is handled automatically

Token Refresh

For connections that support refresh tokens (OAuth 2.0 flow with providers that issue refresh tokens), the system automatically refreshes expired tokens before making API calls. This ensures uninterrupted access to your data.

Troubleshooting

Common Issues

Testing Your Connection

After creating a connection, you can test it by:

1. Creating a REST API Source component
2. Selecting your connection
3. Configuring a simple GET request to a known endpoint (e.g., user profile endpoint)
4. Checking if the response returns valid data

Supported Providers

Universal OAuth works with any OAuth 2.0 compliant provider. Here are some commonly used services:

For providers not listed, you can configure Universal OAuth manually using the provider's OAuth documentation.

Security Best Practices

• Keep secrets confidential - Never share your Client Secret or access tokens
• Use minimal scopes - Only request the permissions your integration actually needs
• Regularly review connections - Remove unused connections to minimize security exposure
• Monitor for unauthorized access - Check your provider's security logs for suspicious activity