refactor: update OAuth token handling to use expires_in instead of ex…

[Jayyk09]

Change OAuth Token Injection API to Use Standard expires_in Format

Problem

The current OAuth token injection API expects expires_at (an absolute timestamp) in the request body, which is non-standard. The OAuth 2.0 specification (RFC 6749) defines that token responses should include expires_in as the number of seconds until expiration, not an absolute timestamp. (Issue #1024)

This forces API users to manually convert the standard expires_in value from OAuth providers into a custom expires_at timestamp:

// Current workaround needed
const expiryDate = new Date(Date.now() + authFields.expires_in * 1000);
const expiresAt = expiryDate.toISOString().replace('Z', ''); // Remove 'Z' to make it timezone-naive

Solution

Update the OAuth token injection API to accept the standard expires_in format (integer seconds) instead of expires_at (datetime string). This allows users to pass OAuth token responses directly to the Airweave API without manual conversion.

Changes

1. Updated Input Schema (backend/airweave/schemas/source_connection.py)

Changed OAuthTokenAuthentication to use expires_in:

• Field name: expires_at → expires_in
• Type: datetime → int
• Description: Updated to indicate standard OAuth2 format
• Validation: Added check to ensure expires_in is positive if provided

2. Updated Service Logic (backend/airweave/core/source_connection_service.py)

Modified _create_with_oauth_token() to store expires_in directly in OAuth credentials:

3. Regenerated OpenAPI Specification (fern/definition/openapi.json)

Updated the API documentation to reflect the new standard-compliant format.

Output Schema (Unchanged)

The output schema (AuthenticationDetails) still returns expires_at as an absolute timestamp for display purposes. This provides:

• Input: Standard OAuth2 format (expires_in in seconds)
• Output: User-friendly absolute timestamp (expires_at)

Testing

Verified the changes by:

1. Checking the updated OpenAPI schema at /docs endpoint
2. Confirming OAuthTokenAuthentication now accepts expires_in (integer)
3. Verifying the running backend accepts the new format

Breaking Changes

⚠️ This is a breaking change for any existing code using OAuth token injection.

Before:

{
  "authentication": {
    "access_token": "...",
    "refresh_token": "...",
    "expires_at": "2025-11-11T20:17:54.670000"
  }
}

After:

{
  "authentication": {
    "access_token": "...",
    "refresh_token": "...",
    "expires_in": 3600
  }
}

Users will need to update their integration code, but this is a one-time change that simplifies their implementation going forward.

Benefits

• ✅ Aligns with OAuth 2.0 RFC 6749 standard
• ✅ Eliminates manual timestamp conversion
• ✅ Consistent with how browser OAuth flow already works internally
• ✅ Allows passing OAuth provider responses directly to Airweave

References

• [OAuth 2.0 RFC 6749 - Access Token Response](https://datatracker.ietf.org/doc/html/rfc6749#section-5.1)
• [OAuth.com - Access Token Response](https://www.oauth.com/oauth2-servers/access-tokens/access-token-response/)

---

Summary by cubic

Switch the OAuth token injection API to use expires_in (seconds) instead of expires_at (timestamp), aligning with OAuth 2.0 and removing manual conversion. This is a breaking change for clients that previously sent expires_at.

• Migration
  • Replace authentication.expires_at with authentication.expires_in (integer seconds) in requests.
  • Responses still return expires_at; no changes needed on read.
  • expires_in must be a positive integer.

^{Written for commit 04204eb. Summary will update automatically on new commits.}

[Jayyk09]

The output schema is unchanged, would you like me to change that as well?

[cubic-dev-ai]

No issues found across 3 files

[Jayyk09]

Unsure as to why the test is failing as it unrelated to the changes I made, or am i mistaken?

The Monke - parallel runners seems to be permission issue with Github actions and the Public API Tests seems to be related rate limiting.