Skip to main content

​
SocialApp

Represents a social application (OAuth client) configured for authentication.

​
Fields

​
provider
CharField
The provider type (e.g., “google”, “github”, “saml”).Max length: 30 characters
​
provider_id
CharField
For providers that support subproviders (OpenID Connect, SAML), this ID identifies the specific instance. Social accounts originating from this app will have their provider field set to provider_id if available, otherwise provider.Max length: 200 characters
Optional: Yes
​
name
CharField
Human-readable name for the application.Max length: 40 characters
​
client_id
CharField
OAuth client ID, app ID, or consumer key.Max length: 191 characters
​
secret
CharField
API secret, client secret, or consumer secret.Max length: 191 characters
Optional: Yes
​
key
CharField
Additional key field for providers that require it.Max length: 191 characters
Optional: Yes
​
settings
JSONField
Additional provider-specific settings stored as JSON.Default: {}
​
sites
ManyToManyField
Associated Django sites where this app can be used. Only available when django.contrib.sites is enabled.Related model: sites.Site
Optional: Yes

​
Methods

​
get_provider()

def get_provider(request) -> Provider
Returns the provider instance for this social app.
​
request
HttpRequest
The Django request object.
​
return
Provider
The provider instance configured with this app.
Example: 
app = SocialApp.objects.get(provider="google")
provider = app.get_provider(request)

​
Manager Methods

​
objects.on_site()

SocialApp.objects.on_site(request) -> QuerySet
Filters social apps available for the current site.
​
request
HttpRequest
The Django request object.
​
return
QuerySet
Social apps configured for the current site, or all apps if sites framework is disabled.
Example: 
available_apps = SocialApp.objects.on_site(request)

​
SocialAccount

Represents a user’s account with a social provider.

​
Fields

​
user
ForeignKey
The local user account associated with this social account.Related model: AUTH_USER_MODEL
On delete: CASCADE
​
provider
CharField
The provider identifier. For accounts from a SocialApp, this equals the app’s provider_id if available, otherwise provider.Max length: 200 characters
​
uid
CharField
The unique identifier for the user at the provider. This is the provider’s user ID.Max length: Configurable via SOCIALACCOUNT_UID_MAX_LENGTH (default: 191)
Unique: Together with provider
​
last_login
DateTimeField
Timestamp of the last login using this social account.Auto-updated: Yes
​
date_joined
DateTimeField
Timestamp when this social account was first connected.Auto-created: Yes
​
extra_data
JSONField
Additional data from the provider (profile information, etc.).Default: {}

​
Methods

​
authenticate()

def authenticate() -> User
Authenticates and returns the user associated with this social account.
​
return
User
The authenticated user object.
Example: 
account = SocialAccount.objects.get(provider="google", uid="123456")
user = account.authenticate()

​
get_profile_url()

def get_profile_url() -> str
Returns the profile URL for this account on the social provider’s site.
​
return
str
The profile URL, or empty string if not available.
Example: 
profile_url = account.get_profile_url()
# "https://github.com/username"

​
get_avatar_url()

def get_avatar_url() -> str
Returns the avatar/profile picture URL from the provider.
​
return
str
The avatar URL, or empty string if not available.
Example: 
avatar_url = account.get_avatar_url()
# "https://avatars.githubusercontent.com/u/123456"

​
get_provider()

def get_provider(request=None) -> Provider
Returns the provider instance for this social account.
​
request
HttpRequest
Optional Django request object.
​
return
Provider
The provider instance.
Example: 
provider = account.get_provider()
print(provider.name)  # "Google"

​
get_provider_account()

def get_provider_account() -> ProviderAccount
Returns the provider-specific account wrapper with additional functionality.
​
return
ProviderAccount
Provider-specific account object.
Example: 
provider_account = account.get_provider_account()
display_name = provider_account.to_str()

​
SocialToken

Stores OAuth tokens for social accounts.

​
Fields

​
app
ForeignKey
The social application this token is for.Related model: SocialApp
On delete: SET_NULL
Optional: Yes
​
account
ForeignKey
The social account this token belongs to.Related model: SocialAccount
On delete: CASCADE
​
token
TextField
The OAuth token. For OAuth1, this is the oauth_token. For OAuth2, this is the access token.
​
token_secret
TextField
The OAuth token secret. For OAuth1, this is the oauth_token_secret. For OAuth2, this is the refresh token.Optional: Yes
​
expires_at
DateTimeField
When the access token expires.Optional: Yes

​
Meta

​
unique_together
tuple
Combination of app and account must be unique.
Example: 
token = SocialToken.objects.get(account=account)
if token.expires_at and token.expires_at < timezone.now():
    # Token expired, refresh needed
    pass

​
SocialLogin

Represents a social user in the process of being logged in. This is a non-model class used during authentication flow.

​
Attributes

​
account
SocialAccount
The social account being logged in. May be unsaved.
​
user
User
The local user being logged in. May be unsaved.
​
token
SocialToken
Optional access token from the authentication handshake.
​
email_addresses
List[EmailAddress]
Email addresses retrieved from the provider.
​
state
dict
State preserved during authentication. May be included in URLs, so do not store secrets here.
​
provider
Provider
The provider instance handling this login.
​
phone
str
Phone number retrieved from the provider, if available.
​
phone_verified
bool
Whether the phone number has been verified by the provider.

​
Methods

​
__init__()

def __init__(
    user=None,
    account: Optional[SocialAccount] = None,
    token: Optional[SocialToken] = None,
    email_addresses: Optional[List[EmailAddress]] = None,
    provider=None,
    phone: Optional[str] = None,
    phone_verified: bool = False,
)
Creates a new SocialLogin instance. Example: 
from allauth.socialaccount.models import SocialLogin, SocialAccount

account = SocialAccount(provider="google", uid="123456")
sociallogin = SocialLogin(account=account, provider=provider)

​
connect()

def connect(request, user) -> None
Connects this social account to an existing user.
​
request
HttpRequest
The Django request object.
​
user
User
The user to connect this social account to.
Example: 
sociallogin.connect(request, request.user)

​
save()

def save(request, connect: bool = False) -> None
Saves the social account and user to the database.
​
request
HttpRequest
The Django request object.
​
connect
bool
Whether this is a connection to an existing user.Default: False
Example: 
sociallogin.save(request)

​
lookup()

def lookup() -> None
Looks up the existing local user account this social login points to, if any. Updates self.user if found. Example: 
sociallogin.lookup()
if sociallogin.is_existing:
    print(f"Found existing user: {sociallogin.user}")

​
serialize()

def serialize() -> Dict[str, Any]
Serializes the social login to a dictionary.
​
return
dict
Dictionary containing all social login data.
Example: 
data = sociallogin.serialize()
# Store in session or cache
request.session['sociallogin'] = data

​
deserialize()

@classmethod
def deserialize(cls, data: Dict[str, Any]) -> SocialLogin
Deserializes a social login from a dictionary.
​
data
dict
Dictionary containing serialized social login data.
​
return
SocialLogin
The deserialized SocialLogin instance.
Example: 
data = request.session.get('sociallogin')
sociallogin = SocialLogin.deserialize(data)

​
get_redirect_url()

def get_redirect_url(request) -> Optional[str]
Returns the URL to redirect to after login.
​
request
HttpRequest
The Django request object.
​
return
str
The redirect URL, or None.
Example: 
redirect_url = sociallogin.get_redirect_url(request)

​
stash_state()

@classmethod
def stash_state(cls, request, state: Optional[Dict[str, Any]] = None) -> str
Stashes state in the session and returns a state ID.
​
request
HttpRequest
The Django request object.
​
state
dict
State dictionary to stash. If None, extracts state from request.
​
return
str
State ID that can be used to retrieve the state later.
Example: 
state = {'next': '/dashboard/', 'process': 'login'}
state_id = SocialLogin.stash_state(request, state)

​
unstash_state()

@classmethod
def unstash_state(cls, request) -> Optional[Dict[str, Any]]
Retrieves and removes the last stashed state from the session.
​
request
HttpRequest
The Django request object.
​
return
dict
The unstashed state dictionary.
Raises:
  • PermissionDenied if no state is found.
Example: 
state = SocialLogin.unstash_state(request)
next_url = state.get('next')

​
Properties

​
is_existing

@property
def is_existing() -> bool
Returns False if this represents a temporary account not yet saved to the database. Example: 
if not sociallogin.is_existing:
    # This is a new account being created
    pass

​
is_headless

@property
def is_headless() -> bool
Returns True if this is a headless (API-based) authentication flow. Example: 
if sociallogin.is_headless:
    # Return JSON response instead of rendering template
    pass

Build docs developers (and LLMs) love

Get started for freeTalk to us