feat(cdk): add api_token interpolation support to SessionTokenAuthenticator

[Ryan Waskewich (rwask)]

Summary

Adds an api_token field to SessionTokenRequestApiKeyAuthenticator that allows flexible token formatting using Jinja interpolation. This enables support for APIs that require non-standard token formats, such as Django REST Framework APIs that expect Authorization: Token <value> instead of Authorization: Bearer <value>.

Changes:

• Added api_token field to the schema with default {{ session_token }} for backward compatibility
• Created InterpolatedSessionTokenProvider class that interpolates a template with the session token value
• Updated factory to always wrap with InterpolatedSessionTokenProvider (using default template when api_token not specified)
• Updated Pydantic models to include the new field
• Added parametrized unit tests for InterpolatedSessionTokenProvider
• Added factory wiring test to verify interpolation is correctly applied

Closes #884

Updates since last revision

• Replaced token_prefix approach with interpolation approach per reviewer feedback
  • Changed from PrefixedTokenProvider with simple string prefix to InterpolatedSessionTokenProvider with Jinja template
  • Changed schema field from token_prefix to api_token with template syntax
  • More flexible: supports arbitrary formatting like "Token {{ session_token }}", "realm=xyz, token={{ session_token }}", etc.
  • Default {{ session_token }} maintains backward compatibility

Review & Testing Checklist for Human

• Verify factory always wraps: The factory now always wraps with InterpolatedSessionTokenProvider, even when api_token is not specified (uses default {{ session_token }}). Verify this doesn't break existing connectors.
• Verify interpolation context: The session_token variable is passed to InterpolatedString.eval() via kwargs. Confirm this works correctly with the CDK's Jinja evaluation.
• Backward compatibility: Existing manifests without api_token should work unchanged since it defaults to {{ session_token }} which just returns the raw token.
• End-to-end test: Consider testing with a real DRF API (like the Lean Hotel System API mentioned in the issue) to verify Authorization: Token <value> format works correctly.

Recommended test plan:

1. Create a test connector manifest using SessionTokenAuthenticator with api_token: "Token {{ session_token }}"
2. Verify the Authorization header is sent as Token <session_token> rather than the raw token value
3. Verify existing connectors using SessionTokenAuthenticator without api_token continue to work

Example manifest snippet:

authenticator:
  type: SessionTokenAuthenticator
  login_requester:
    type: HttpRequester
    url: https://api.example.com/auth/
    http_method: POST
    request_body:
      type: RequestBodyJsonObject
      value:
        username: "{{ config['username'] }}"
        password: "{{ config['password'] }}"
  session_token_path:
    - token
  expiration_duration: PT1H
  request_authentication:
    type: ApiKey
    inject_into:
      type: RequestOption
      field_name: Authorization
      inject_into: header
    api_token: "Token {{ session_token }}"

Notes

• Link to Devin run: https://app.devin.ai/sessions/3d827009266142d3b99d96425cbaa02e
• Requested by: Ryan Waskewich (@rwask)

Summary by CodeRabbit

• New Features
  • Added configurable API token templates for session-based authentication, allowing integration developers to customize how session tokens are formatted in authorization headers. Supports flexible templates such as "Bearer {{ session_token }}", "Token {{ session_token }}", and custom formats to accommodate diverse API authentication requirements.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

Testing This CDK Version

You can test this version of the CDK using the following:

# Run the CLI from this branch:
uvx 'git+https://github.com/airbytehq/airbyte-python-cdk.git@devin/1769528869-session-token-prefix#egg=airbyte-python-cdk[dev]' --help

# Update a connector to use the CDK from this branch ref:
cd airbyte-integrations/connectors/source-example
poe use-cdk-branch devin/1769528869-session-token-prefix

PR Slash Commands

Airbyte Maintainers can execute the following slash commands on your PR:

• /autofix - Fixes most formatting and linting issues
• /poetry-lock - Updates poetry.lock file
• /test - Runs connector tests with the updated CDK
• /prerelease - Triggers a prerelease publish with default arguments
• /poe build - Regenerate git-committed build artifacts, such as the pydantic models which are generated from the manifest JSON schema in YAML.
• /poe <command> - Runs any poe command in the CDK environment

📚 Show Repo Guidance

Helpful Resources

• CDK API Reference

📝 Edit this welcome message.

[github-actions]

PyTest Results (Fast)

3 832 tests  +6   3 820 ✅ +6   6m 28s ⏱️ -6s
    1 suites ±0      12 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit a1f173f. ± Comparison against base commit 9b23860.

♻️ This comment has been updated with latest results.

[github-actions]

PyTest Results (Full)

3 835 tests   3 823 ✅  10m 32s ⏱️
    1 suites     12 💤
    1 files        0 ❌

Results for commit a1f173f.

♻️ This comment has been updated with latest results.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces support for configurable token templates in session-based authentication. A new InterpolatedSessionTokenProvider class wraps session tokens with customizable templates (e.g., "Token {{ session_token }}", "Bearer {{ session_token }}"), enabling authentication with APIs requiring specific token formatting in ApiKey authentication mode.

Changes

Cohort / File(s)	Summary
Token Provider Implementation airbyte_cdk/sources/declarative/auth/token_provider.py	Introduces InterpolatedSessionTokenProvider class that composes a nested session token provider with a string template, interpolating the session token into the template on each token fetch. Also adds docstring to InterpolatedStringTokenProvider.
Schema Definitions airbyte_cdk/sources/declarative/declarative_component_schema.yaml	Adds api_token field to both ApiKeyAuthenticator and SessionTokenRequestApiKeyAuthenticator definitions, with default value "{{ session_token }}" and examples supporting token prefixes like "Token " and "Bearer ".
Component Models airbyte_cdk/sources/declarative/models/declarative_component_schema.py	Adds api_token optional field to SessionTokenRequestApiKeyAuthenticator model with template examples and descriptive documentation.
Parser & Factory airbyte_cdk/sources/declarative/parsers/model_to_component_factory.py	Imports InterpolatedSessionTokenProvider and modifies create_session_token_authenticator to wrap the session token provider with template interpolation when not using Bearer type.
Unit Tests unit_tests/sources/declarative/auth/test_token_provider.py	Adds new test cases for InterpolatedSessionTokenProvider, validating template interpolation with various token prefix formats.
Parser Tests unit_tests/sources/declarative/parsers/test_model_to_component_factory.py	Updates existing test assertions to reflect InterpolatedSessionTokenProvider wrapping behavior and adds test case verifying custom API token templates.

Sequence Diagram(s)

sequenceDiagram
    participant App as Application
    participant IST as InterpolatedSessionTokenProvider
    participant STP as SessionTokenProvider
    participant API as API Server
    
    App->>IST: get_token()
    activate IST
    IST->>STP: get_token()
    activate STP
    STP->>API: POST /login (or equivalent)
    API-->>STP: {token: "abc123"}
    STP-->>IST: "abc123"
    deactivate STP
    IST->>IST: interpolate("Token {{ session_token }}", session_token="abc123")
    IST-->>App: "Token abc123"
    deactivate IST

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.22% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding api_token interpolation support to SessionTokenAuthenticator, which aligns with the primary objective of enabling flexible token formatting via Jinja interpolation.
Linked Issues check	✅ Passed	The PR successfully addresses issue #884 by implementing api_token field with Jinja interpolation for token formatting and wrapping session token providers with InterpolatedSessionTokenProvider to support formats like 'Token {{ session_token }}', meeting the primary coding requirement.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the api_token interpolation feature: schema updates, new InterpolatedSessionTokenProvider class, factory wiring, model updates, and comprehensive tests. No unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}