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.

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.

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.

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"
	}
}