Authentication

Bizon supports multiple authentication methods for connecting to source APIs. Configure authentication in the source.authentication section of your pipeline configuration.

Authentication Types

Type	Use Case	Description
oauth	OAuth 2.0 APIs	Token refresh with client credentials
api_key	API key authentication	Bearer or custom header token
bearer	Bearer tokens	Simple bearer token (alias for api_key)
basic	HTTP Basic Auth	Username/password encoding
cookies	Session-based	Cookie and header injection

OAuth 2.0

For APIs that use OAuth 2.0 with refresh tokens. Bizon automatically refreshes expired access tokens.

source:
  name: hubspot
  stream: contacts
  authentication:
    type: oauth
    params:
      token_refresh_endpoint: https://api.hubapi.com/oauth/v1/token
      client_id: your-client-id
      client_secret: your-client-secret
      refresh_token: your-refresh-token

Parameters:

Parameter	Required	Default	Description
token_refresh_endpoint	Yes	-	URL to refresh the token
client_id	Yes	-	OAuth client ID
client_secret	Yes	-	OAuth client secret
refresh_token	No	-	Refresh token for obtaining new access tokens
scopes	No	-	List of OAuth scopes
token_expiry_date	No	-	Initial token expiry date
access_token_name	No	access_token	Name of access token in response
expires_in_name	No	expires_in	Name of expiry field in response
grant_type	No	refresh_token	OAuth grant type
refresh_request_body	No	-	Additional body parameters for refresh request
response_field_path	No	-	dpath to token in nested response

Advanced Example:

authentication:
  type: oauth
  params:
    token_refresh_endpoint: https://oauth.example.com/token
    client_id: BIZON_ENV_CLIENT_ID
    client_secret: BIZON_ENV_CLIENT_SECRET
    refresh_token: BIZON_ENV_REFRESH_TOKEN
    scopes:
      - read:contacts
      - read:companies
    grant_type: refresh_token
    access_token_name: access_token
    expires_in_name: expires_in

API Key / Bearer Token

For APIs that accept a static token in the Authorization header.

Bearer Token

source:
  name: notion
  stream: pages
  authentication:
    type: api_key
    params:
      token: your-api-token

Custom Header

source:
  name: custom_api
  stream: data
  authentication:
    type: api_key
    params:
      token: your-api-token
      auth_method: Token
      auth_header: X-API-Key

Parameters:

Parameter	Required	Default	Description
token	Yes	-	The API token or key
auth_method	No	Bearer	Prefix before the token (e.g., Bearer, Token, ApiKey)
auth_header	No	Authorization	HTTP header name

Generated Header:

Authorization: Bearer your-api-token

Or with custom settings:

X-API-Key: Token your-api-token

Basic HTTP Authentication

For APIs that use HTTP Basic authentication with username and password.

source:
  name: kafka
  stream: topic
  authentication:
    type: basic
    params:
      username: your-username
      password: your-password

Parameters:

Parameter	Required	Default	Description
username	Yes	-	Username for authentication
password	No	""	Password (can be empty)
auth_method	No	Basic	Auth method prefix
auth_header	No	Authorization	HTTP header name

Generated Header:

The username and password are Base64 encoded:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Cookies Authentication

For APIs that require session cookies or custom headers.

source:
  name: internal_api
  stream: data
  authentication:
    type: cookies
    params:
      cookies:
        session_id: abc123
        auth_token: xyz789
      headers:
        X-Custom-Header: custom-value

Parameters:

Parameter	Required	Default	Description
cookies	Yes	-	Dictionary of cookie name-value pairs
headers	No	{}	Additional headers to include

Using Environment Variables

Never hardcode secrets in your configuration files. Use environment variables with the BIZON_ENV_ prefix:

authentication:
  type: oauth
  params:
    client_id: BIZON_ENV_CLIENT_ID
    client_secret: BIZON_ENV_CLIENT_SECRET
    refresh_token: BIZON_ENV_REFRESH_TOKEN

Set the environment variables before running:

export BIZON_ENV_CLIENT_ID="your-client-id"
export BIZON_ENV_CLIENT_SECRET="your-client-secret"
export BIZON_ENV_REFRESH_TOKEN="your-refresh-token"

bizon run config.yml

No Authentication

Some public APIs don’t require authentication:

source:
  name: pokeapi
  stream: pokemon
  # No authentication section needed

Choosing an Authentication Type

API Type	Recommended Auth
OAuth 2.0 APIs (HubSpot, Google, Salesforce)	oauth
Simple API keys (Notion, Stripe)	api_key
Kafka with SASL	basic
Legacy session-based APIs	cookies
Public APIs	None

Next Steps

• Sources Overview - Configure source connectors
• CLI Reference - Run pipelines with environment variables
• Configuration Reference - Complete YAML options