API Key Authentication

API Key authentication allows you to create API Keys for your end users as well as your organizations in order to protect requests they make to your product.

In a typical web application, you can setup authentication in the browser. API Key authentication allows your users to make requests outside of the browser, such as CLIs, cURL, etc.

API Token Types

There are three different kinds of API Keys that PropelAuth can generate, based on the desired use case.

Basic Usage

First, your users create an API Key via our configurable hosted pages (you can also create them manually via our APIs if you want to manage it yourself)

Next, when a user makes a request to your product, they will send this key in their request.

Finally, your product makes a request to our validation API endpoints to make sure that the token is valid, and we return the user or organization that the token was issued to, along with any relevant metadata. Our validation endpoints accept bearer tokens or just the key itself, so the choice on how you ask your users to include the token is up to you!

Enabling API Keys

First enable API Key Authentication in your Project. In the API Key Settings section of the dashboard, make sure that you enable your preferred feature, either Personal or Organization API Keys, or both.

Generating API Keys

Click on the Preview button on the top right of your PropelAuth dashboard and click on the API Key hosted page or pages you enabled. These pages are where you will redirect your customers to create their API Keys.

Just like the rest of our hosted pages, they are fully customizable and will appear under your domain name.

Alternatively, you can also use the Create API Key Backend API to generate API keys for your users and organizations.

Validate Requests from your customers

Once a customer has generated an API Key for their requests, they can then send that key in the header of their requests to your product. You can then verify that the request is coming from a real user by hitting our validation endpoints, and receive from PropelAuth any relevant metadata about the requester.

@router.get("/api/whoami")
async def whoAmI(request: Request):
	try:
		api_key = auth.validate_api_key(request.headers.get('authorization'))
		return api_key
	except Exception:
		raise HTTPException(status_code=403, detail="Not Authorized")

If the validation is successful, this would return:

{
	"user": {
		"user_id":"98cef184-7c15-45c5-8918-8c2295aa7ffe",
		"email":"test@propelauth.com",
		"email_confirmed":true,
		"has_password":true,
		"picture_url":"https://img.propelauth.com/2a27d237-db8c-4f82-84fb-5824dfaedc87.png",
		"locked":false,
		"enabled":true,
		"mfa_enabled":false,
		"can_create_orgs":false,
		"created_at":1685487933,
		"last_active_at":1685494460,
		"org_id_to_org_info":{
			...
		},
		"update_password_required":false
	},
	"metadata": {
		"how_do_i_set_this": "you can set the metadata on API key creation or update"
	}
}

API Key Usage Charts

Projects with the Advanced API Keys Add-On can view dashboards and charts to track API key usage across users and organizations. Usage is recorded by each request made to one of our validation endpoints. Charts are provided for:

• An organization's total Organization API key usage
• A user's total Personal API key usage
• A single API Key's usage

API Key Expiration

You can also set the expiration options you want to provide your users when they create API keys. The available options are two weeks, one month, three months, six months, one year, and never. When an API key expires, the Validate API Key request will return an Expired token error.

API Key Rate Limiting

Projects with the Advanced API Keys Add-On can enforce rate limits on their user's and organization's API key usage. You can configure rate limits for both Personal and Organization API Keys in the API Key Settings page in your PropelAuth Dashboard.

Rate limits are enforced at the user and organization level, not at the individual API key level. This means that the rate limit applies collectively to all API keys associated with a single user or organization.

For example, if a user exceeds the rate limit using API Key 1, switching to API Key 2 will not bypass the limit.

Rate Limiting Error

What happens when one of your users or organizations hits a rate limit? When you go to validate their API Key via one of the validation endpoints, instead of returning a success response we'll return an exception error. You can handle this error like so:

@router.get("/api/whoami")
async def whoAmI(request: Request):
	try:
		api_key = auth.validate_api_key(request.headers.get('authorization'))
		return api_key
	except EndUserApiKeyRateLimitedException as e:
		raise HTTPException(status_code=429, detail=f"Please wait {e.args[0]['wait_seconds']} seconds before trying again.")
	except Exception:
		raise HTTPException(status_code=403, detail="Not Authorized")

Archiving And Deleting API Keys

Archiving an API Key

Archiving an API Key hides the API Key from your users in the hosted pages and prevents it from being validated. However, all charts and usage data for the API Key will remain accessible via the PropelAuth Dashboard.

When a user deletes an API Key in the hosted pages, they are actually archiving the API Key. An API Key cannot be fully deleted by your users and organizations.

The Delete API Key API also only archives the API Key, ensuring that API Key data is not accidentally deleted.

Deleting an API Key

Deleting an API Key is similar to archiving as it hides the API Key from your users and prevents it from being validated.

However, it also removes the API Key from the PropelAuth Dashboard as well as all usage data on that API Key. The only remaining data on that API Key will be the API Key Created and API Key Deleted events in the Audit Logs. API Keys can only be fully deleted via the PropelAuth Dashboard.