Skip to content

Python Backend Integration

PropelAuth's Python library provides all the building blocks you need to add authentication to any Python backend. For most Python frameworks, like FastAPI, Django, and Flask, we have built out libraries specifically for them, and they will provide a more first-class experience than this library.

Quick example

The following example creates a route which can only be accessed from logged-in users.

from propelauth_py import init_base_auth

auth = init_base_auth("YOUR_AUTH_URL", #(1)
                      "YOUR_API_KEY") #(2)

auth_header = # get authorization header in the form `Bearer {TOKEN}`
try:
   user = auth.validate_access_token_and_get_user(auth_header)
   print("Logged in as", user.user_id)
except UnauthorizedException:
   print("Invalid access token")
  1. The base URL where your authentication pages are hosted. You can find your Auth URL 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.

How it works

The front-end receives an access token. This access token is provided in an Authorization header when an HTTP request is made.

PropelAuth provides you with metadata that you use to validate the access token and figure out who it belongs to. The complexity of fetching the metadata and validating the tokens is hidden in the Python library.

Installation

$ pip install propelauth_py

Initialize

init_base_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 validate_access_token_and_get_user and validate_access_token_and_get_user_with_org.

from propelauth_py import init_base_auth

auth = init_base_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

User

A user returned by validate_access_token_and_get_user or validate_access_token_and_get_user_with_org.

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
legacy_user_id The original ID of the user, if the user was migrated from an external source

The values of org_id_to_org_member_info are OrgMemberInfo's, with the following fields/functions:

OrgMemberInfo fields/properties Description
org_id The id of the org
org_name The name of the org
user_assigned_role The user's role within the organization. See Roles and Permissions for more details.
user_is_role(role: str): bool Returns True if the user's role within the organization matches the role passed in
user_is_at_least_role(role: str): bool Returns True if the user's role within the organization is at least the role passed in. If the hierarchy of roles is Owner => Admin => Member, specifying "Admin" will return True for Admins and Owners, but False for Members.
user_has_permission(permission: str): bool Return True if the user has a specific permission. The users' permissions are derived from their role within this organization.
user_has_all_permissions(permissions: List[str]): bool Return True if the user has all the specified permissions. The users' permissions are derived from their role within this organization.

validate_access_token_and_get_user

This function takes in the Authorization HTTP header and verifies the request was made by a valid user. It expects the header to be in the format Bearer ACCESS_TOKEN. If the Authorization HTTP header is malformed or doesn't contain a valid access token, an UnauthorizedException is thrown.

auth_header = # get authorization header in the form `Bearer {TOKEN}`
try:
   user = auth.validate_access_token_and_get_user(auth_header)
   print("Logged in as", user.user_id)
except UnauthorizedException:
   print("Invalid access token")

validate_access_token_and_get_user_with_org

This function will verify that a request was made by a valid user AND that user is in an organization.

Argument Description
Authorization HTTP Header It expects the header to be in the format Bearer ACCESS_TOKEN. If the Authorization HTTP header is malformed or doesn't contain a valid access token, an UnauthorizedException is thrown.
Required Org ID A string representing the organization ID to check that the user is a member of. If the user is NOT a member of the specified organization, a ForbiddenException is thrown.

The return value has a user and a org_member_info containing the following properties:

OrgMemberInfo fields/properties Description
org_id The id of the org
org_name The name of the org
user_assigned_role The user's role within the organization. See Roles and Permissions for more details.
user_is_role(role: str): bool Returns True if the user's role within the organization matches the role passed in
user_is_at_least_role(role: str): bool Returns True if the user's role within the organization is at least the role passed in. If the hierarchy of roles is Owner => Admin => Member, specifying "Admin" will return True for Admins and Owners, but False for Members.
user_has_permission(permission: str): bool Return True if the user has a specific permission. The users' permissions are derived from their role within this organization.
user_has_all_permissions(permissions: List[str]): bool Return True if the user has all the specified permissions. The users' permissions are derived from their role within this organization.

Roles and Permissions

A user has a Role within an organization. By default, the available roles are Owner, Admin, or Member, but these can be configured. These roles are also hierarchical, so Owner > Admin > Member.

Roles allow you to control what different users can do within your product. If you want to check a user's role, you can use auth.validate_access_token_and_get_user_with_org_by_minimum_role or auth.validate_access_token_and_get_user_with_org_by_exact_role which will very the request was made by a valid user, that user is in the specified organization, AND that the user's within the organization matches what was passed in.

Permissions are arbitrary strings associated with a role. For example, can_view_billing, ProductA::CanCreate, and ReadOnly are all valid permissions. The PropelAuth dashboard allows you to set up these permissions.

You can use auth.validate_access_token_and_get_user_with_org_by_permission or auth.validate_access_token_and_get_user_with_org_by_all_permissions to check for a given permission.

All of these functions, just like validate_access_token_and_get_user_with_org, will take in an authorization header and an organization ID. The last parameter is either a role, permission, or list of permissions depending on the function.

API calls

In addition to protecting API routes, you can make requests to PropelAuth to fetch more information about your users or organizations. You can also create new users, update user metadata, and more.

See Python Library Reference for more information on available functionality.

Next Steps

Done with your backend? Next you can deploy to production.