Skip to content

docs: add Python tutorial for refresh token OAuth in multi-tenant Apify Actors#2549

Open
foxck016077 wants to merge 1 commit into
apify:masterfrom
foxck016077:tutorial/refresh-token-oauth-multi-tenant
Open

docs: add Python tutorial for refresh token OAuth in multi-tenant Apify Actors#2549
foxck016077 wants to merge 1 commit into
apify:masterfrom
foxck016077:tutorial/refresh-token-oauth-multi-tenant

Conversation

@foxck016077
Copy link
Copy Markdown

Summary

Adds a new tutorial under sources/academy/tutorials/python/ covering the refresh token OAuth pattern for Apify Actors that call per-user Google APIs (Gmail, Calendar, Drive) without hosting an OAuth callback URL or storing user identity on the Apify side.

The tutorial walks through:

  1. Google Cloud setup using the Desktop app OAuth client type (which removes the redirect URL requirement)
  2. Generating the refresh token via google-auth-oauthlib's run_local_server flow
  3. Exchanging the refresh token for a short-lived access token at runtime
  4. Defining INPUT_SCHEMA with isSecret: true on the credential fields
  5. An optional dry_run boolean so first-time users can preview the dataset shape before committing to the full OAuth setup

Motivation

This pattern is used in production today for Actors that call per-user Google APIs, but the docs don't yet cover it. Currently a developer searching "Apify actor Gmail OAuth" finds no end-to-end tutorial. Related: apify/apify-mcp-server#741 asks for server-level OAuth/SSO between MCP client and Apify (a different layer than what this tutorial covers), but readers landing on that issue may also be looking for the Actor-level credential delegation pattern.

Pattern correctness

Verified against a production Actor running this exact pattern: foxck016077/apify-gmail-inbox-intel (MIT, listed on Apify Store as foxck/gmail-inbox-intel).

Standards checklist

  • Sentence case headings, no gerund headings
  • Front matter complete: title, description (154 chars), sidebar_position (3), slug
  • Bold used only for UI elements (Apify Console buttons, Google Cloud sections)
  • All code blocks have language tags (python, json)
  • US English, active voice, imperative tone, no sales language
  • No em dashes (hyphen with spaces only)
  • Internal links use relative paths (e.g. /platform/actors/development/actor-definition/input-schema)
  • No new images required

Compatibility

  • No changes to existing tutorials
  • New file only; no rename or move
  • sidebar_position: 3 slots after process_data_using_python.md (position 2)
  • Slug /python/refresh-token-oauth-multi-tenant-actors is unique

Happy to revise scope, tone, file placement, or pull cross-references if there's a better home for it in the Academy structure.

Adds a Python tutorial covering the refresh token OAuth pattern for Actors that
call per-user Google APIs (Gmail, Calendar, Drive) without hosting an OAuth
callback URL or storing user identity on the Apify side.

Covers Google Cloud Desktop app client setup, generating the refresh token via
google-auth-oauthlib's run_local_server, exchanging at runtime for a short-lived
access token, marking credential fields as isSecret in INPUT_SCHEMA, and an
optional dry_run mode so first-time users can preview the dataset shape before
committing to the OAuth setup.

Relates to apify/apify-mcp-server#741 (which asks for server-level OAuth/SSO,
not Actor-level credential delegation, but readers may land here looking for
the Actor-level pattern).
foxck016077 pushed a commit to foxck016077/apify-gmail-inbox-intel that referenced this pull request May 20, 2026
…ibution

Adds links to 3 dev.to posts published today (mamoru douyin learning post,
PWYW vs $99 lifetime answer to @tokidigital, and the reader-centric refresh
token OAuth tutorial). The OAuth tutorial entry also references the open PR
#2549 to apify/apify-docs that promotes it as an official Academy tutorial.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants