Skip to Content


A basic walk through of how to use Purple Authentication in your project.

Creating an App

The first step is to create a new App in the dashboard. You will need to give the app a name, decided whether to allow refresh tokens, and where to redirect users who authenticate using magic links. You also set a threshold to be notified if you are nearing your allotted authentications. (Billing is done by pre-purchasing a certain number of authentication attempts for your account which never expire)

App creation form
Just creating a test app.

Once you send the form, your app is saved as a document in MongoDB associated with your account (which was auto-created on your first login). The backend will generate a unique id and secret keys for your app and show you the created app. You will need your app id to implement the authentication on your site, but it's not a secret so it can be viewed at any time. You will also need the public portion of the generated keys. If you use my authentication client for Python, this is handled automatically.

Created app
Look there's an app now!

Updating and Deleting

In addition to viewing your created app, you can also edit the app's attributes (except the app id), rotate the secret keys, and delete the app. Editing the name and URLs for the app shouldn't break anything and users likely won't notice.

Edit the app attributes
Editable attributes are highlighted in...well, purple of course!

Rotating the keys will immediately invalidate all active user sessions and everyone will need to re-authenticate. You will also need to ensure that the new keys are downloaded anywhere they are needed and removed from any caches. This is your only real recourse if tokens become compromised. However, re-authenticating someone isn't that big of a deal. They would have had to sign back in tomorrow anyway since refresh tokens only last 24 hours.

Edit the app attributes
I want to make sure you mean it.

To prevent accidental deletion, which could be catastrophic for a production application, I've enabled deletion protection by default. It is straightforward to since the system will walk you through it, but very difficult to do by accident.

Edit the app attributes
I really want to make sure you mean it.

Using Purple Authentication

Now that you have an app setup, you will need to add it to your site. You can either access the REST API directly, or use my authentication client for python, or access the REST API directly. FastAPI (which is the basis for this system) generates documentation automatically, so the best way to understand the api is to look at them.

App creation form
They're acutally quite nice to use. You can even try the API out right in the docs.

Briefly, your site/app sends a request to my server with your app id from the dashboard and a user email. I will generate either a secret code or magic link and store that hashed secret with the email and app id in a redis cache for five minutes and email it to the user.

Link Authentication

If the user/you chose magic link authentication, all they have to do is click the link in their email. They will first be taken to Purple Authentication to have their secret code authenticated, then be redirected to the configured URL depending on whether the authentication was successful or not. If it was successful, an id token and refresh token (if enabled) will be included in the query string of the URL. You can then save that in a cookie (or whatever) and use it to authenticate the user.

App creation form
It's ugly, but it's one click!
Code Authentication

If the user/you chose one time code authentication, they will enter the code they were sent on your site, which you then submit for validation. If it is the correct code and hasn't expired, the backend will send back a payload with the user's new tokens to be saved on the client.

App creation form
I send the user to a code form and stick their email address in a hidden input. If you don't submit the email address and code, the server will have no idea if it's right.
Validating Tokens

All tokens generated by Purple Auth are JWTs. ID Tokens can be validated using the public portion of your app key accessible on the API. Tokens all use the ES256 algorithm. User email is in the "sub" claim. Everything else is standard. The API docs show where to get the public key. The easiest way will be to use my authentication client, but you can also send tokens to the API for validation. This is going to be very slow at scale compared to using the client or doing it yourself.

Refresh tokens can only be authenticated by sending them to the refresh endpoint. If the token is valid, a new ID Token will be generated and sent back.

User Management and Authorization

I don't do it. Purple Auth handles authentication only. This system will verify that someone is the email address they say they are, but nothing more. It doesn't handle any authorization, doesn't store information about users, and doesn't limit who can log in. If you want any of that, you have to do it yourself. Anyone with an email address can be authenticated against any app unless there are restrictions somewhere else in the chain.

Portal Authentication

Of course, you have to authenticate yourself in order to access your apps dashboard and create/edit apps. Naturally, Purple Auth uses itself for authentication. Purple Auth uses purple-auth-client to access itself and authenticate users. It's open source, so if you want to see a reference implementation (or the whole thing), you can! Check out the portal folder. You can even host it yourself if you want. The only real difference from a production app is that it's been hard-coded to app id 0 and cannot be deleted, and its own url is used as the endpoint for the auth client (rather than This is really just for easier development and testing.