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. Those libraries will provide a more first-class experience than this library.
For the full Python Library Reference, click here.
Quick example
The following example creates a route which can only be accessed from logged-in users.
from propelauth_py import init_base_auth
# You can find your Auth URL and API key under the Backend Integration
# section for your project at https://app.propelauth.com.
auth = init_base_auth("YOUR_AUTH_URL", "YOUR_API_KEY")
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")
How it works
For a detailed description of what’s going on under the hood, see here.
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", "YOUR_API_KEY")
Protect API routes
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.
Otherwise, a User is returned.
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:
| Field | 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. |
User
A user returned by validate_access_token_and_get_user and 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 orgIdToOrgMemberInfo are OrgMemberInfo’s, with the following fields/functions:
| Field | 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.