Feature/oauth client credentials 2026

[lvalics]

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.