django-rest-social-auth: exchanging an OAuth code for an authenticated user

The problem it solves, stated narrowly

The README describes the goal as having a resource that will do a very simple thing, take the OAuth code from a social provider, for example Facebook, and return the authenticated user. Then it says that plainly, that's it. The motivation section explains that the author could not find such a utility for Django REST framework, and that there are packages, for example django-rest-auth, that take an access token rather than a code. The distinction is the whole product. An access token exchange means the server has to hold the provider's access token and call the provider's API to identify the user, and it needs the access token to be obtained somewhere. A code exchange means the client performs the provider's redirect flow, receives the short-lived code, and posts it to your API, and your server then trades that code for a token itself. The second is the flow the OAuth 2.0 authorisation code grant describes, and it is the flow that keeps a provider token out of the browser. The README also notes that the author had worked with python-social-auth and would like to use it again, now that it is split into social-core and social-app-django, and that in fact most of the work is done by that package. So this is a thin integration layer that connects an existing, capable social auth library to the REST framework's authentication classes, and the author's own framing is that it brings a little help to integrate the two.

Requirements and supported versions

The requirements list is precise about the version matrix, and that precision is a good sign for a package that sits between other people's libraries. Python 3.10, 3.11, 3.12, 3.13 and 3.14 are supported. Django 5.2, 6.0 and 6.1 are supported. Django REST framework must be at least 3.9 and below 4.0. The social auth stack needs social-auth-core at 5.0 or newer and below 6.0, and social-auth-app-django at 6.0 or newer and below 7.0. Two optional dependencies enable two of the authentication styles, with djangorestframework-simplejwt at 5.0.0 or newer for JWT and django-rest-knox at 5.1.0 and below 6.0.0 for Knox. The requirements file shipped for installation reflects the core set.

django>=5.2
djangorestframework<4.0
social-auth-core>=5.0,<6.0
social-auth-app-django>=6.0,<7.0

The upper bounds are the interesting part. Pinning below the next major of each dependency is what lets the package say it supports a range, and it is also the reason an application that needs a newer version of one of those libraries will find itself blocked until this package catches up. The release history shows it does move, with v10.0.0 from 2026-08-08, v9.0.0 from 2025-05-30 and v8.3.0 from 2024-01-08, and the last push to the repository was on 2026-08-08. The package is MIT licensed and published on PyPI as rest_social_auth.

Installing it and wiring the settings

The quick start begins with a single install.

    pip install rest-social-auth

Then the Django settings. The installed apps list needs rest_framework, and the authtoken app if you use token authentication, social_django for the social auth side, rest_social_auth for this package, and knox only if you use django-rest-knox.

    INSTALLED_APPS = (
        ...
        'rest_framework',
        'rest_framework.authtoken',  # only if you use token authentication
        'social_django',  # django social auth
        'rest_social_auth',  # this package
        'knox',  # Only if you use django-rest-knox
    )

The social auth settings themselves are the standard ones, with the client id, the client secret, an optional scope list and optional extra profile parameters, and the authentication backends list naming the provider backend plus the model backend.

    SOCIAL_AUTH_FACEBOOK_KEY = 'your app client id'
    SOCIAL_AUTH_FACEBOOK_SECRET = 'your app client secret'
    SOCIAL_AUTH_FACEBOOK_SCOPE = ['email', ]  # optional
    SOCIAL_AUTH_FACEBOOK_PROFILE_EXTRA_PARAMS = {'locale': 'ru_RU'}  # optional


    AUTHENTICATION_BACKENDS = (
        'social_core.backends.facebook.FacebookOAuth2',
        # and maybe some others ...
        'django.contrib.auth.backends.ModelBackend',
    )

The provider-specific prefix in each setting name is the provider name, so Facebook is shown here and other providers follow the same pattern with their own backends from social_core. The README points at the social auth documentation for the full configuration reference, and notes that there are additional optional settings beyond these.

After the settings, a migration step is needed.

    python manage.py migrate

Four URL sets, one per authentication style

The fourth step of the quick start is to include the URLs, and the README says to choose at least one. There are four sets, and each is a single include in your URL configuration, which is a nice touch since the choice of authentication style does not change your router beyond one line.

    path('api/login/', include('rest_social_auth.urls_session')),

    path('api/login/', include('rest_social_auth.urls_token')),

    path('api/login/', include('rest_social_auth.urls_jwt_pair')),

    path('api/login/', include('rest_social_auth.urls_knox')),

There is also a sliding JWT variant, included from rest_social_auth.urls_jwt_sliding, and the README notes that the two JWT sets can be used together. The distinction between the pair and sliding styles is delegated to the simplejwt documentation, with a link to that project's description of the difference between the token types. The choice of which to include is a decision about what your clients already handle rather than about the package, since each style produces a different credential on the way back.

What the endpoints return

The fifth step says you are ready to login users, and the examples given are for OAuth 2.0. The request body is the same in every case, a provider name and the code.

            {
                "provider": "facebook",
                "code": "AQBPBBTjbdnehj51"
            }

What comes back differs. The session endpoint returns the user data, with the username, the email and other user fields, plus a session id in cookies. The token endpoint returns a token, and there is a separate token_user endpoint that returns the user data and the token together.

            {
                "token": "68ded41d89f6a28da050f882998b2ea1decebbe0"
            }

            {
                "username": "Alex",
                "email": "[email protected]",
                // other user data
                "token": "68ded41d89f6a28da050f882998b2ea1decebbe0"
            }

The JWT endpoints follow the same pattern with the pair and pair-user variants, and the difference is the token type, with the JWT pair response carrying an extra refresh token alongside the access token.

        {
            "token": "...",
            "refresh": "..."
        }

The Knox endpoints are the same shape again with the token being a Django Rest Knox token, and the README notes that django-rest-knox must be installed to use them. The user model itself is taken from settings.AUTH_USER_MODEL, so the package does not impose a user model on you, which matters in an application that has already defined a custom one. The pattern across all of these is worth stating plainly, because it is the design of the package in miniature, one request shape and several response shapes.

How the project is built and tested

The repository layout is that of a package with a working example and a containerised development environment. There is a rest_social_auth/ package directory, an example_project/ directory, a tests/ directory, a scripts/ directory, a Dockerfile, a Makefile, a tox.ini, a pytest.ini, a setup.py, a setup.cfg, a MANIFEST.in, requirements files for the core, the optional and the test dependencies, and a RELEASE_NOTES.md that the README links for release notes. The setup.py is unusual in a way worth reading, because it turns the script into a small task runner. If the last argument is build it removes the build and dist directories and runs the PEP 517 frontend to produce both an sdist and a wheel. If it is publish it uploads both artefacts to PyPI in a single twine call, with a comment explaining that this way the credentials are asked for only once. If it is tag it creates an annotated git tag for the current version and pushes the tags. The package metadata names it rest_social_auth, describes it as Django rest framework resources for social auth, requires Python 3.10 or newer, and uses the keywords django social auth rest login signin signup oauth.

The Dockerfile shows the shape of the development container.

FROM python:3.13

RUN mkdir -p /opt/runtime/
ADD scripts/* /opt/runtime/

RUN useradd -ms /bin/bash appuser
USER appuser

ENTRYPOINT ["/opt/runtime/entrypoint.sh"]

It runs a non-root user, which is the right default, and the Makefile drives the same tasks either inside the container or natively, with targets for the example project, the test suite, tox, a shell and a native test run. The native test target sets the PYTHONPATH to the example project and runs pytest with warnings ignored, and the native lint target is run before it as part of the test target. The project also carries lint and test workflow badges and a coverage badge, so the checks are run on every change rather than left to a contributor.

Where django-rest-social-auth is the wrong choice

The first limit is that the package is narrow by design, and narrowness cuts both ways. It handles the code exchange and nothing else, so the rest of a social login flow, the redirect, the state parameter, the provider's own session handling and the account linking logic, is still your responsibility or social-core's. The second is the dependency ceiling. Every library in the stack is pinned below its next major, and Django itself is pinned to three versions, so a project on a newer Django or a newer social auth core waits for this package to move. The third is that the social auth ecosystem itself is ageing. python-social-auth is no longer maintained under that name and has been split, the README notes one of the optional dependencies does not work on Python 3.6 which is a small sign of how long these pieces have been around, and a package that sits on top of an unmaintained base inherits that risk. The fourth is that OAuth has moved on since the authorisation code grant the package implements, and although the README's examples are explicitly labelled as being for OAuth 2.0, a project that needs the newer flows for a mobile client with public clients and PKCE is not served by this package. The fifth is the security surface itself. The package accepts a code and a provider name from the client and exchanges them, which means it is a place where a token is minted from client input, and the details of how that exchange is validated, including state and redirect handling, live in the social auth libraries rather than here. A reviewer reading only this repository's code is not reading the code that decides whether the exchange is safe.

Editorial conclusion

Adopt django-rest-social-auth if you want social signin in a Django REST framework API and you would rather exchange an OAuth code than implement an access-token exchange yourself. Skip it if your API already has a working token exchange flow, since this package is deliberately narrow. Verify first which Django and Django REST framework versions you are on, that the social auth core packages you need are installed, and that the authentication style you choose is the one your client already understands.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. st4lk/django-rest-social-auth on GitHub