René's URL Explorer Experiment

Title: Feature/oauth client credentials 2026 by lvalics · Pull Request #787 · Shopify/shopify_python_api · GitHub

Open Graph Title: Feature/oauth client credentials 2026 by lvalics · Pull Request #787 · Shopify/shopify_python_api

X Title: Feature/oauth client credentials 2026 by lvalics · Pull Request #787 · Shopify/shopify_python_api

Description: Complete OAuth 2.0 Client Credentials Grant Support for Shopify API 2026-01+ Overview This PR adds comprehensive OAuth 2.0 Client Credentials Grant support required for Shopify API version 2026-01 and later, including automatic version detection, token expiration tracking, automatic refresh, and scope filtering for multi-API apps. Background Shopify API 2026-01+ Changes: Apps created in the new Shopify Dev Dashboard use OAuth 2.0 Client Credentials Grant (RFC 6749 Section 4.4) Tokens expire after 24 hours (86,399 seconds) Multiple API types can be configured: Admin API, Customer Account API, Storefront API /admin/oauth/access_token endpoint only supports Admin API scopes Previous Limitations: No built-in support for client credentials flow No automatic token refresh mechanism No way to filter scopes when apps have multiple API types configured Risk of authentication failures during long-running operations Features 1. OAuth 2.0 Client Credentials Grant Support New Methods: Session.request_token_client_credentials() - Exchange client credentials for access token Session.request_access_token() - Smart method that automatically selects correct OAuth flow based on API version New Exception: OAuthException - OAuth-specific errors with detailed error information Automatic Version Detection: API versions >= 2026-01 automatically use client credentials flow Older versions continue using authorization code grant Legacy request_token() raises ValidationException for API versions >= 2026-01 Example: import shopify shopify.Session.setup(api_key="client_id", secret="client_secret") session = shopify.Session("mystore.myshopify.com", "2026-01") # Automatically uses correct flow based on API version response = session.request_access_token() # Returns: {'access_token': 'shpca_...', 'scope': '...', 'expires_in': 86399} 2. Token Expiration Tracking and Automatic Refresh New Methods: Session.is_token_expired(buffer_seconds=300) - Check if token is expired or expiring soon Session.refresh_token_if_needed(buffer_seconds=300) - Automatically refresh token if expired or expiring soon Session.refresh_token() - Manually force token refresh regardless of expiration status Token Lifecycle Management: Session tracks token_obtained_at and token_expires_at timestamps Default 5-minute buffer before expiration ensures proactive refresh Prevents authentication failures during long-running operations Example: # Set up session with existing token session = shopify.Session("mystore.myshopify.com", "2026-01", "existing_token") session.token_obtained_at = datetime.now() - timedelta(hours=23) session.token_expires_at = datetime.now() + timedelta(hours=1) # Automatically refresh if needed (with 5-minute buffer) result = session.refresh_token_if_needed() if result: print(f"Token refreshed! New token: {result['access_token']}") else: print("Token still valid, no refresh needed") # Or force refresh manually result = session.refresh_token() print(f"Token refreshed! Expires in {result['expires_in']} seconds") 3. OAuth Scope Filtering Support Problem Solved: When apps have multiple API types configured (Admin API + Customer Account API + Storefront API), requesting tokens through /admin/oauth/access_token fails because that endpoint only supports Admin API scopes. Solution: All OAuth methods now accept optional scope parameter to request specific scopes. New Functionality: request_token_client_credentials(scope=None) request_access_token(scope=None) refresh_token_if_needed(scope=None) refresh_token(scope=None) Scope Normalization: Comma-separated scopes automatically converted to space-separated for OAuth 2.0 spec compliance Example: "read_products,write_products" → "read_products write_products" Example: # App has Admin API + Customer Account API scopes configured shopify.Session.setup(api_key="client_id", secret="client_secret") session = shopify.Session("mystore.myshopify.com", "2026-01") # Request ONLY Admin API scopes (even though app has Customer Account API configured) response = session.request_access_token( scope="read_products write_products read_orders write_orders" ) # Success! Token granted with Admin API scopes only # Auto-refresh with specific scopes result = session.refresh_token_if_needed( scope="read_products write_products read_orders write_orders" ) Use Case - Mixed API Types: Shopify app configuration: Admin API: - read_products, write_products - read_orders, write_orders Customer Account API: - customer_read_metaobjects ← Would cause error without scope filtering Storefront API: - unauthenticated_read_metaobjects Before (fails): # Tries to request ALL scopes through /admin/oauth/access_token response = session.request_access_token() # Error: 'customer_read_metaobjects' is not a valid access scope After (works): # Request only Admin API scopes response = session.request_access_token( scope="read_products write_products read_orders write_orders" ) # Success! ✓ Complete Usage Example import shopify from datetime import datetime, timedelta # Setup credentials shopify.Session.setup(api_key="client_id", secret="client_secret") # Create session for 2026-01 API session = shopify.Session("mystore.myshopify.com", "2026-01") # 1. Get initial token with Admin API scopes only response = session.request_access_token( scope="read_products write_products read_orders write_orders" ) print(f"Token: {response['access_token']}") print(f"Expires in: {response['expires_in']} seconds") print(f"Scopes: {response['scope']}") # Session now has token and expiration tracking print(f"Token obtained at: {session.token_obtained_at}") print(f"Token expires at: {session.token_expires_at}") # 2. Use token for API calls shopify.ShopifyResource.activate_session(session) shop = shopify.Shop.current() print(f"Shop: {shop.name}") # 3. Check token expiration if session.is_token_expired(buffer_seconds=300): print("Token is expired or expiring within 5 minutes") # 4. Auto-refresh if needed (before long operation) result = session.refresh_token_if_needed( scope="read_products write_products read_orders write_orders" ) if result: print("Token was refreshed proactively") # 5. Manual refresh (e.g., after permission changes) result = session.refresh_token( scope="read_products write_products read_orders write_orders" ) print(f"Token manually refreshed! New token expires in {result['expires_in']}s") Testing Comprehensive Test Coverage: ✅ Client credentials token request (success & error cases) ✅ Automatic version detection (2026-01+ vs older versions) ✅ Token expiration tracking and timestamps ✅ Token expiration checking with buffer ✅ Automatic refresh when token expired ✅ Manual force refresh ✅ Scope parameter in all OAuth methods ✅ Scope normalization (comma → space) ✅ Default behavior without scope parameter ✅ Backward compatibility with existing code Test Statistics: 15+ new test cases All existing tests pass 100% backward compatible Backward Compatibility ✓ No Breaking Changes All new features are additive and backward compatible: # Existing code works without modifications session = shopify.Session("mystore.myshopify.com", "2025-10") response = session.request_access_token(params) # Uses authorization code grant # New API version automatically uses new flow session = shopify.Session("mystore.myshopify.com", "2026-01") response = session.request_access_token() # Uses client credentials grant # Scope parameter is optional response = session.request_access_token() # No scope = all configured scopes response = session.request_access_token(scope="read_products") # Filtered scopes Migration Guide For Existing Apps (API < 2026-01) No changes required. Your code continues to work as before. For New Apps (API >= 2026-01) Option 1 - Simple (no scope filtering): shopify.Session.setup(api_key="client_id", secret="client_secret") session = shopify.Session("mystore.myshopify.com", "2026-01") response = session.request_access_token() # Gets all configured scopes Option 2 - With automatic refresh: shopify.Session.setup(api_key="client_id", secret="client_secret") session = shopify.Session("mystore.myshopify.com", "2026-01") # Get initial token session.request_access_token() # Before long operations, auto-refresh if needed session.refresh_token_if_needed() # Use session for API calls shopify.ShopifyResource.activate_session(session) Option 3 - With scope filtering (multi-API apps): shopify.Session.setup(api_key="client_id", secret="client_secret") session = shopify.Session("mystore.myshopify.com", "2026-01") # Request only Admin API scopes response = session.request_access_token( scope="read_products write_products read_orders write_orders" ) # Auto-refresh with same scopes session.refresh_token_if_needed( scope="read_products write_products read_orders write_orders" ) Implementation Details RFC 6749 Compliance: Implements OAuth 2.0 Client Credentials Grant (Section 4.4) Form-encoded request body (application/x-www-form-urlencoded) Proper error handling per OAuth 2.0 spec Security: Client credentials never exposed in URLs Tokens transmitted over HTTPS only Proper scope validation and filtering Error Handling: OAuthException for OAuth-specific errors (401, 400, etc.) Detailed error messages from Shopify included HTTP status codes preserved for debugging Checklist OAuth 2.0 Client Credentials Grant implementation (RFC 6749 Section 4.4) Automatic API version detection Token expiration tracking (token_obtained_at, token_expires_at) Token expiration checking with configurable buffer Automatic token refresh (refresh_token_if_needed) Manual token refresh (refresh_token) Scope filtering for all OAuth methods Scope normalization (comma → space) New OAuthException for OAuth errors Comprehensive test coverage (15+ tests) Updated CHANGELOG Backward compatibility maintained All existing tests pass No breaking changes Benefits This PR enables developers to: ✅ Build apps for Shopify API 2026-01+ using Client Credentials Grant ✅ Automatically handle token expiration and refresh ✅ Prevent authentication failures during long-running operations ✅ Configure multiple API types in a single Shopify app ✅ Use Customer Account API scopes alongside Admin API scopes ✅ Follow OAuth 2.0 best practices for scope filtering ✅ Seamlessly migrate from older API versions Related: Implements OAuth 2.0 support for apps created in the new Shopify Dev Dashboard, which use Client Credentials Grant instead of Authorization Code Grant for server-to-server authentication.

Open Graph Description: Complete OAuth 2.0 Client Credentials Grant Support for Shopify API 2026-01+ Overview This PR adds comprehensive OAuth 2.0 Client Credentials Grant support required for Shopify API version 2026-01 ...

X Description: Complete OAuth 2.0 Client Credentials Grant Support for Shopify API 2026-01+ Overview This PR adds comprehensive OAuth 2.0 Client Credentials Grant support required for Shopify API version 2026-01 ...

Opengraph URL: https://github.com/Shopify/shopify_python_api/pull/787

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width