From ea143e133538e5869c527c9b3a06d29f36377bb4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michal=20=C4=8Ciha=C5=99?= <michal@cihar.com>
Date: Wed, 7 Oct 2026 10:18:02 +0200
Subject: [PATCH] docs(facebook): explain access token retrieval in Django

Show how to retrieve and renew stored Facebook tokens so Django users can make Graph API requests after login. Clarify pipeline and permission requirements.

Fixes https://github.com/python-social-auth/social-app-django/issues/201
---
 docs/backends/facebook.rst | 40 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/backends/facebook.rst b/docs/backends/facebook.rst
index 907b0171..0435ed39 100644
--- a/docs/backends/facebook.rst
+++ b/docs/backends/facebook.rst
@@ -24,6 +24,33 @@ Python Social Auth provides multiple backends for Facebook authentication:
 - **FacebookAppOAuth2** (``social_core.backends.facebook.FacebookAppOAuth2``) - For Facebook Canvas Applications
 - **FacebookLimitedLogin** (``social_core.backends.facebook_limited.FacebookLimitedLogin``) - For Facebook Limited Login (iOS SDK)
 
+Access tokens in Django
+-----------------------
+
+After a user logs in with ``FacebookOAuth2``, the default authentication
+pipeline stores the Facebook access token in ``UserSocialAuth.extra_data``.
+In a Django view, retrieve it from the authenticated user's linked Facebook
+account::
+
+    social = request.user.social_auth.get(provider='facebook')
+    access_token = social.access_token
+    # Equivalent: social.extra_data.get('access_token')
+
+This example assumes the user has a linked Facebook account. If they do not,
+the query raises ``UserSocialAuth.DoesNotExist``; ask them to connect Facebook
+before retrieving a token. If your application allows multiple Facebook
+accounts per user, select the intended account by its ``uid`` as well.
+
+If you customize ``SOCIAL_AUTH_PIPELINE``, retain
+``social_core.pipeline.social_auth.load_extra_data`` so that the token is
+saved. You do not need to add ``access_token`` to
+``SOCIAL_AUTH_FACEBOOK_EXTRA_DATA``.
+
+Use this token for server-side Facebook Graph API requests. The data available
+depends on the permissions granted to the token. Request additional permissions
+with ``SOCIAL_AUTH_FACEBOOK_SCOPE``; ``SOCIAL_AUTH_FACEBOOK_PROFILE_EXTRA_PARAMS``
+controls which profile fields are requested during login.
+
 Token renewal
 -------------
 
@@ -34,6 +61,19 @@ for an explicit exchange or ``social.get_access_token(strategy)`` to exchange
 when the stored access token has expired. See :ref:`oauth-token-renewal` for
 expiry handling and renewal failures.
 
+For expiry-aware retrieval in a Django view::
+
+    from social_django.utils import load_strategy
+
+    social = request.user.social_auth.get(provider='facebook')
+    access_token = social.get_access_token(load_strategy(request))
+
+Reading ``social.access_token`` returns the stored token without attempting
+renewal. ``get_access_token()`` attempts renewal when the stored expiry
+indicates that the token has expired. It does not guarantee that Facebook
+still accepts the token: handle renewal and Graph API failures, and ask the
+user to authenticate with Facebook again when necessary.
+
 OAuth2
 ------