Authentication Methods
  • 2 Minutes to read
  • Dark
    Light
  • PDF

Authentication Methods

  • Dark
    Light
  • PDF

Article summary

Blueprint Available in private preview!

We are excited to announce that our new Blueprint engine are now available to a select group of preview customers!

If you're interested in joining the private preview, click here to request access.

# Authentication in Rivery

Overview

This guide explains how to authenticate your API connections in Rivery using various authentication methods. Rivery supports OAuth 2.0, basic authentication, bearer tokens, and provides secure token management for all methods.


Supported Authentication Methods

MethodUse Case
basic_httpSimple username/password authentication
bearerStatic bearer tokens
oauth2Secure token-based flows (e.g., client credentials, refresh token, etc.)

Authentication Parameters

Purpose: Manage secure API connections.

Authentication parameters define how a connector will authenticate API calls. These can include basic authentication, token-based authentication, or Bearer token authentication.

Basic Authentication Example

- name: "connectToAPI"
  type: "authentication"
  auth_type: "basic_http"
  fields:
    - name: "username"
      type: "string"
      value: "your_rivery_mail"
    - name: "password"
      type: "string"
      value: "look at 1password"

Token-Based Authentication Example

- name: "connectToAPI"
  type: "authentication"
  auth_type: "bearer"
  fields:
    - name: "bearer_token"
      type: "string"
      value: "your_bearer_token"

How It Works in YAML:

  • The connectToAPI parameter contains authentication details.
  • The fields section includes credentials such as usernames, passwords, API keys, or tokens.
  • The auth_type specifies the authentication method (basic_http, bearer, etc.).

OAuth 2.0 Authentication

Rivery supports multiple OAuth 2.0 flows and automatically manages token acquisition, refresh, and injection into your API calls.

Supported OAuth 2.0 Flows

FlowWhen to Use
client_credentialsServer-to-server APIs (no user login)
refresh_tokenLong-running user-authorized applications
authorization_codeApplications with user login & redirection

OAuth2 YAML Configuration Example

Client Credentials

interface_parameters:
  section:
    source:
      - name: "my_api_auth"
        type: "authentication"
        auth_type: "oauth2"
        oauth2_settings:
          grant_type: "client_credentials"
          token_url: "https://auth.example.com/token"
          is_basic_auth: false
        fields:
          - name: "client_id"
            type: "string"
            value: "your_client_id"
          - name: "client_secret"
            type: "string"
            value: "your_client_secret"
            is_encrypted: true

With Basic Auth

oauth2_settings:
  grant_type: "client_credentials"
  token_url: "https://api.example.com/token"
  is_basic_auth: true

Refresh Token

oauth2_settings:
  grant_type: "refresh_token"
  token_url: "https://auth.example.com/token"
fields:
  - name: "refresh_token"
    value: "your_refresh_token"
    is_encrypted: true

Authorization Code

oauth2_settings:
  grant_type: "authorization_code"
  token_url: "https://auth.example.com/token"
fields:
  - name: "code"
    value: "your_auth_code"
  - name: "redirect_uri"
    value: "https://yourapp.com/callback"

OAuth2 Parameter Reference

OAuth2 Settings

KeyRequiredDescription
grant_typeYesOAuth flow type (client_credentials, refresh_token, authorization_code)
token_urlYesURL to obtain the access token
is_basic_authNoSends client credentials via Authorization header (default: false)

Fields

NameWhen RequiredDescription
client_idAlwaysYour app's client ID
client_secretAlwaysYour app's client secret
refresh_tokenFor refresh_token flowToken obtained from previous login
codeFor authorization_codeCode received after redirect login
redirect_uriFor authorization_codeRedirect URI used in authentication

Security & Token Handling

  • Rivery automatically refreshes tokens before they expire.
  • Supports token expiry detection via expires_in, exp, or expires_at.
  • If no expiry is defined, the default is 1 hour.

Encrypt Your Secrets

Always mark secrets as encrypted:

- name: "client_secret"
  value: "your_secret"
  is_encrypted: true

Basic Auth Format

Without Basic Auth

grant_type=client_credentials&client_id=xxx&client_secret=yyy

With Basic Auth

Authorization: Basic base64(client_id:client_secret)
grant_type=client_credentials

Error Messages & Fixes

ErrorFix
Token refresh failedVerify your refresh token
Refresh token requiredEnsure refresh_token field is present
Connection issueCheck token URL or network configuration

Best Practices

  • Always set is_encrypted: true for sensitive values like client_secret and refresh_token.
  • Use descriptive name fields for maintainability.
  • Test with a static token first to validate base connectivity before configuring full OAuth.
  • Document which authentication type is required for each connector clearly.

Was this article helpful?