Skip to content

Django Rest Framework Library Reference

Installation

$ pip install propelauth-django-rest-framework

Initialize

init_auth performs a one-time initialization of the library. It will verify your api_key is correct and fetch the metadata needed to verify access tokens in IsUserAuthenticated, AllowAny, and IsUserInOrg.

from propelauth_django_rest_framework import init_auth

auth = init_auth("YOUR_AUTH_URL", #(1)
                 "YOUR_API_KEY") #(2)
  1. The base URL where your authentication pages are hosted. You can find this under the Backend Integration section for your project at https://app.propelauth.com.
  2. You can manage your api keys under the Backend Integration section for your project.

Protect API routes

IsUserAuthenticated

A permission that will verify the request was made by a valid user. Specifically, it will:

  1. Check that a valid access token was provided. If not, the request is rejected with a 401 status code.
  2. Set request.propelauth_user with the user's information.
from propelauth_django_rest_framework import init_auth, current_user

auth = init_auth("YOUR_AUTH_URL", "YOUR_API_KEY")

@api_view(['GET'])
@permission_classes([auth.IsUserAuthenticated])
def whoami(request):
   return HttpResponse(request.propelauth_user.user_id)

or you can use it in class-based views:

class WhoAmIView(APIView):
   permission_classes = [auth.IsUserAuthenticated]

   def get(self, request):
      return HttpResponse(request.propelauth_user.user_id)

AllowAny

Similar to IsUserAuthenticated, except if an access token is missing or invalid, the request is allowed to continue, but request.propelauth_user will be None.

Note that this will still set request.propelauth_user if a valid access token is provided.

class OptionalUserView(APIView):
    permission_classes = [auth.AllowAny]

    def get(self, request):
        if request.propelauth_user is None:
            return HttpResponse("none")
        return HttpResponse(request.propelauth_user.user_id)

request.propelauth_user

A per-request value that contains user information for the user making the request. It's set by one of IsUserAuthenticated, AllowAny, or IsUserInOrg.

Property Description
user_id The id of the user
org_id_to_org_member_info A dictionary of org ids to metadata about the org. Includes all orgs that the user is in

The values of org_id_to_org_member_info have these properties:

org_id_to_org_member_info properties Description
org_id The id of the org
org_name The name of the org
user_role The user's role within the org. See UserRole for more details.

IsUserInOrg

A function that returns a permission that will verify the request was made by a valid user that belongs to a specific organization.

IsUserInOrg Argument Description
req_to_org_id A function that takes in the request and outputs the org_id to require the user to be a member of. If none is specified, it will check for a path param org_id by checking request.GET.get('org_id', '').
minimum_required_role If specified, IsUserInOrg will check both that the user is a member of the organization, and that their role is >= minimum_required_role. If not, the request is rejected with a 403 Forbidden error.
@api_view(['GET'])
@permission_classes([auth.IsUserInOrg(minimum_required_role=UserRole.Admin)])
def admins_only(request):
   message = f"You are an admin or owner of {request.propelauth_org.org_name}"
   return HttpResponse(message)

Specifically, it will:

  1. Check that a valid access token was provided. If not, the request is rejected with a 401 status code.
  2. Set request.propelauth_user with the user's information.
  3. Find an id for an organization within the request. By default, it will check for a path parameter org_id.
  4. Check that the user is a member of that organization. If not, the request is rejected with a 403 status code.
  5. (Optionally) Check that the user's role in that organization is >= minimum_required_role. If not, the request is rejected with a 403 status code.
  6. Set request.propelauth_org (scoped to the current request) with the organization's information for this user.

request.propelauth_org

A per-request value that contains org information for the user making the request. It's set by IsUserInOrg.

Property Description
org_id The id of the org
org_name The name of the org
user_role The user's role within the org. See UserRole for more details.

Fetch user metadata by id

# auth object somes from init_auth
auth.fetch_user_metadata_by_user_id(user_id, include_orgs=False)

Successful response:

{
    "user_id":            "e9d3520f-836e-403c-82c2-09843517e1ce",
    "email":              "user@example.com",
    "email_confirmed":    true,

    "username":           "example", // (1)
    "first_name":         "first", // (2)
    "last_name":          "last", // (3)
    "picture_url":        "https://...", // (4)

    "locked":             false,
    "enabled":            true,
    "mfa_enabled":        false,

    "created_at":         1645131680,
    "last_active_at":     1650654711,

    // Only returned if include_orgs = true
    "org_id_to_org_info": { // (5)
        "2ef0e1fc-234f-4dc0-a50c-35adb1bbb7e4": {
            "org_id": "2ef0e1fc-234f-4dc0-a50c-35adb1bbb7e4",
            "org_name": "ExampleOrganization",
            "user_role": "Owner"
        }
    }
}
  1. Optional: Only returned if you have the field enabled as part of your user schema
  2. Optional: Only returned if you have the field enabled as part of your user schema
  3. Optional: Only returned if you have the field enabled as part of your user schema
  4. Optional: Only returned if you have the field enabled as part of your user schema
  5. True if the user's account is locked for security purposes.
  6. Includes all organizations that the user is a member of

Fetch user metadata by email

# auth object somes from init_auth
auth.fetch_user_metadata_by_email(email, include_orgs=False)

Successful response is the same as fetch_user_metadata_by_user_id, expect it takes an email as an argument.

Fetch user metadata by username

# auth object somes from init_auth
auth.fetch_user_metadata_by_username(email, include_orgs=False)

Successful response is the same as fetch_user_metadata_by_user_id, expect it takes a username as an argument.

Batch fetch users by ids

# auth object somes from init_auth
user_id_to_metadata = auth.fetch_batch_user_metadata_by_user_ids([
    "1be238f3-5908-4c51-b3bf-e53dd763047e",
    "beb00acf-6e48-435d-8388-3758607ec01b",
    "941c99e5-3530-4475-bd0f-bbc5d06603c3"
], include_orgs=False)

user_id_to_metadata looks like

Any IDs that don't have a match are not returned. Duplicate users are only returned once.

{
    "1be238f3-5908-4c51-b3bf-e53dd763047e": {
        "user_id": "e9d3520f-836e-403c-82c2-09843517e1ce",
        "email": "user@example.com", 
        "email_confirmed": true, 

        "username": "example", // (1)
        "first_name": "first", // (2)
        "last_name": "last", // (3)
        "picture_url": "https://...", // (4)

        "locked": false, // (5)
        "enabled": true,
        "mfa_enabled": false,

        "created_at": 1645131680,
        "last_active_at": 1650654711,

        // Only returned if include_orgs = true
        "org_id_to_org_info": { // (6)
            "2ef0e1fc-234f-4dc0-a50c-35adb1bbb7e4": {
                "org_id": "2ef0e1fc-234f-4dc0-a50c-35adb1bbb7e4",
                "org_name": "ExampleOrganization",
                "user_role": UserRole.Owner,
            }
        }
    },
    "beb00acf-6e48-435d-8388-3758607ec01b": {
        //...
    }
}
  1. Optional: Only returned if you have the field enabled as part of your user schema
  2. Optional: Only returned if you have the field enabled as part of your user schema
  3. Optional: Only returned if you have the field enabled as part of your user schema
  4. Optional: Only returned if you have the field enabled as part of your user schema
  5. True if the user's account is locked for security purposes.
  6. Includes all organizations that the user is a member of

Batch fetch users by emails

# auth object somes from init_auth
auth.fetch_batch_user_metadata_by_emails(["a@example.com", "b@example.com"], include_orgs=True)

Successful response is the same as Batch fetch users by ids, but the keys are matching email addresses

Batch fetch users by usernames

# auth object somes from init_auth
auth.fetch_batch_user_metadata_by_usernames(["usera", "userb", "userc"], include_orgs=True)

Successful response is the same as Batch fetch users by ids, but the keys are matching usernames

Search for users

# auth object somes from init_auth
auth.fetch_users_by_query(page_size=10, page_number=0, order_by=UserQueryOrderBy.CREATED_AT_ASC,
                          email_or_username=None, include_orgs=False):
Argument Description
page_size The number of results to return at a time. Must be between 1 and 100, default 10.
page_number Used to page over results
order_by How to order the results. See UserQueryOrderBy for options
email_or_username Searches for partial matches within email addresses or usernames. port would match a user with email address support@propelauth.com.
include_orgs Whether or not to include the user's organization information in the response. Default false

Successful response:

{
    "total_users": 103, 
    "current_page": 0, 
    "page_size": 10, 
    "has_more_results": true,
    "users": [{
        // See (1) for example users
    }, {
        // There will be 10 users in this response
    }]
}
  1. Example user in response

Fetch users in organization

# auth object somes from init_auth
auth.fetch_users_in_org(org_id, page_size=10, page_number=0, include_orgs=False)
Argument Description
org_id The organization to fetch users for
page_size The number of results to return at a time. Must be between 1 and 100, default 10.
page_number Used to page over results
include_orgs Whether or not to include the user's organization information in the response. Default false

Successful response:

{
    "total_users": 43, 
    "current_page": 0, 
    "page_size": 10, 
    "has_more_results": true,
    "users": [{
        // See (1) for example users
    }, {
        // There will be 10 users in this response, all in the specified organization
    }]
}
  1. Example user in response

Create User

# auth object somes from init_auth
auth.create_user(email, email_confirmed=False, send_email_to_confirm_email_address=True,
                 password=None, username=None, first_name=None, last_name=None)
Argument Description
email The user's email address
email_confirmed Whether the email address should start off as already confirmed. If false, the user is required to confirm the email address before they sign in.
send_email_to_confirm_email_address Whether we should send an email immediately to confirm the user's email address. If false, the user will get a confirmation email when they first sign in.
password Optional password. If unset, the user can set it themselves via their account page
username Optional username. Can only be used if username is enabled in your user schema
first_name Optional first name. Can only be used if name is enabled in your user schema
last_name Optional last name. Can only be used if name is enabled in your user schema

Successful response:

{
    "user_id": "b5f667fb-e51a-49c6-a396-711e62948689"
}

Update User Email

# auth object somes from init_auth
# Returns true if it was successful, false if the user was not found
auth.update_user_email(user_id, new_email, require_email_confirmation):
Argument Description
new_email New email address for this user
require_email_confirmation Whether the new email address requires confirmation. If true, an email will be sent to the new email address to confirm. If false, the users email address will be updated and confirmed immediately.

Update User Metadata

# auth object somes from init_auth
# Returns true if it was successful, false if the user was not found
auth.update_user_metadata(user_id, username=None, first_name=None, last_name=None):
Argument Description
username Optional username. Can only be used if username is enabled in your user schema
first_name Optional first name. Can only be used if name is enabled in your user schema
last_name Optional last name. Can only be used if name is enabled in your user schema

Fetch an organization

# auth object somes from init_auth
org = auth.fetch_org(org_id)

Successful response:

{
    "org_id": "d488996d-8ccc-4101-b5f2-131f5f09ddb6"
    "name": "OneOfYourCustomers"
}

Fetch all organizations

# auth object somes from init_auth
auth.fetch_org_by_query(page_size=10, page_number=0, order_by=OrgQueryOrderBy.CREATED_AT_ASC):
Argument Description
page_size The number of results to return at a time. Must be between 1 and 100, default 10.
page_number Used to page over results
order_by How to order the results. See OrgQueryOrderBy for options

Successful response:

{
    "total_orgs": 21, 
    "current_page": 0, 
    "page_size": 10, 
    "has_more_results": true,
    "orgs": [{
        "org_id": "d488996d-8ccc-4101-b5f2-131f5f09ddb6",
        "name": "OneOfYourCustomers"
    }, {
        // There will be 10 orgs in this response
    }]
}

UserRole

An enum of roles within an organization. Values, in order of highest to lowest, include

UserRole.Owner
UserRole.Admin
UserRole.Member