Flow¶
This page will present you a complete registration and authentication flow once you've setup FastAPI Users. Each example will be presented with a cURL and an axios example.
1. Registration¶
First step, of course, is to register as a user.
Request¶
Response¶
You'll get a JSON response looking like this:
{
"id": "4fd3477b-eccf-4ee3-8f7d-68ad72261476",
"email": "king.arthur@camelot.bt",
"is_active": true,
"is_superuser": false
}
Info
Several things to bear in mind:
- If you have defined other required fields in your
Usermodel (like a first name or a birthdate), you'll have to provide them in the payload. - The user is active by default.
- The user cannot set
is_activeoris_superuseritself at registration. Only a superuser can do it by PATCHing the user.
2. Login¶
Now, you can login as this new user.
You can generate a login route for each authentication backend. Each backend will have a different response.
Bearer + JWT¶
Request¶
const formData = new FormData();
formData.set('username', 'king.arthur@camelot.bt');
formData.set('password', 'guinevere');
axios.post(
'http://localhost:8000/auth/jwt/login',
formData,
{
headers: {
'Content-Type': 'multipart/form-data',
},
},
)
.then((response) => console.log(response))
.catch((error) => console.log(error));
Warning
Notice that we don't send it as a JSON payload here but with form data instead. Also, the email is provided by a field named username.
Response¶
You'll get a JSON response looking like this:
{
"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiNGZkMzQ3N2ItZWNjZi00ZWUzLThmN2QtNjhhZDcyMjYxNDc2IiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTg3ODE4NDI5fQ.anO3JR8-WYCozZ4_2-PQ2Ov9O38RaLP2RAzQIiZhteM",
"token_type": "bearer"
}
You can use this token to make authenticated requests as the user king.arthur@camelot.bt. We'll see how in the next section.
Cookie + JWT¶
Request¶
const formData = new FormData();
formData.set('username', 'king.arthur@camelot.bt');
formData.set('password', 'guinevere');
axios.post(
'http://localhost:8000/auth/cookie/login',
formData,
{
headers: {
'Content-Type': 'multipart/form-data',
},
},
)
.then((response) => console.log(response))
.catch((error) => console.log(error));
Warning
Notice that we don't send it as a JSON payload here but with form data instead. Also, the email is provided by a field named username.
Response¶
You'll get an empty response. However, the response will come with a Set-Cookie header (that's why we added the -v option in cURL to see them).
set-cookie: fastapiusersauth=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiYzYwNjBmMTEtNTM0OS00YTI0LThiNGEtYTJhODc1ZGM1Mzk1IiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTg3ODE4OTQ3fQ.qNA4oPVYhoqrJIk-zvAyEfEVoEnP156G30H_SWEU0sU; HttpOnly; Max-Age=3600; Path=/; Secure
You can make authenticated requests as the user king.arthur@camelot.bt by setting a Cookie header with this cookie.
Tip
The cookie backend is more suited for browsers, as they handle them automatically. This means that if you make a login request in the browser, it will automatically store the cookie and automatically send it in subsequent requests.
3. Get my profile¶
Now that we can authenticate, we can get our own profile data. Depending on your authentication backend, the method to authenticate the request will vary. We'll stick with JWT from now on.
Request¶
export TOKEN="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiNGZkMzQ3N2ItZWNjZi00ZWUzLThmN2QtNjhhZDcyMjYxNDc2IiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTg3ODE4NDI5fQ.anO3JR8-WYCozZ4_2-PQ2Ov9O38RaLP2RAzQIiZhteM";
curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X GET \
http://localhost:8000/users/me
const TOKEN = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiNGZkMzQ3N2ItZWNjZi00ZWUzLThmN2QtNjhhZDcyMjYxNDc2IiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTg3ODE4NDI5fQ.anO3JR8-WYCozZ4_2-PQ2Ov9O38RaLP2RAzQIiZhteM';
axios.get(
'http://localhost:8000/users/me', {
headers: {
'Authorization': `Bearer ${TOKEN}`,
},
})
.then((response) => console.log(response))
.catch((error) => console.log(error));
Response¶
You'll get a JSON response looking like this:
{
"id": "4fd3477b-eccf-4ee3-8f7d-68ad72261476",
"email": "king.arthur@camelot.bt",
"is_active": true,
"is_superuser": false
}
Tip
If you use one of the dependency callable to protect one of your own endpoint, you'll have to authenticate exactly in the same way.
4. Update my profile¶
We can also update our own profile. For example, we can change our password like this.
Request¶
Response¶
You'll get a JSON response looking like this:
{
"id": "4fd3477b-eccf-4ee3-8f7d-68ad72261476",
"email": "king.arthur@camelot.bt",
"is_active": true,
"is_superuser": false
}
Info
Once again, the user cannot set is_active or is_superuser itself. Only a superuser can do it by PATCHing the user.
5. Become a superuser 🦸🏻♂️¶
If you want to manage the users of your application, you'll have to become a superuser.
The very first superuser can only be set at database level: open it through a CLI or a GUI, find your user and set the is_superuser column/property to true.
5.1. Get the profile of any user¶
Now that you are a superuser, you can leverage the power of superuser routes. You can for example get the profile of any user in the database given its id.
Request¶
Response¶
You'll get a JSON response looking like this:
{
"id": "4fd3477b-eccf-4ee3-8f7d-68ad72261476",
"email": "king.arthur@camelot.bt",
"is_active": true,
"is_superuser": false
}
5.1. Update any user¶
We can now update the profile of any user. For example, we can promote it as superuser.
Request¶
Response¶
You'll get a JSON response looking like this:
{
"id": "4fd3477b-eccf-4ee3-8f7d-68ad72261476",
"email": "king.arthur@camelot.bt",
"is_active": true,
"is_superuser": true
}
5.2. Delete any user¶
Finally, we can delete a user.
Request¶
Response¶
You'll get an empty response.
6. Logout¶
We can also end the session.
Request¶
Response¶
You'll get an empty response.
Conclusion¶
That's it! You now have a good overview of how you can manage the users through the API. Be sure to check the Routes page to have all the details about each endpoints.