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¶
+curl \
+-H "Content-Type: application/json" \
+-X POST \
+-d "{\"email\": \"king.arthur@camelot.bt\",\"password\": \"guinevere\"}" \
+http://localhost:9000/users/register
+axios.post('http://localhost:9000/users/register', {
+ email: 'king.arthur@camelot.bt',
+ password: 'guinevere',
+})
+.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
+}
+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.
+Each authentication backend will produce a single route. For example, the JWT backend will produce the /users/login/jwt route. Each backend will have a different response.
JWT backend¶
+Request¶
+curl \
+-H "Content-Type: multipart/form-data" \
+-X POST \
+-F "username=king.arthur@camelot.bt" \
+-F "password=guinevere" \
+http://localhost:9000/users/login/jwt
+const formData = new FormData();
+formData.set('username', 'king.arthur@camelot.bt');
+formData.set('password', 'guinevere');
+axios.post(
+ 'http://localhost:9000/users/login/jwt',
+ 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:
+{
+ "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiNGZkMzQ3N2ItZWNjZi00ZWUzLThmN2QtNjhhZDcyMjYxNDc2IiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTg3ODE4NDI5fQ.anO3JR8-WYCozZ4_2-PQ2Ov9O38RaLP2RAzQIiZhteM"
+}
+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 backend¶
+Request¶
+curl \
+-v \
+-H "Content-Type: multipart/form-data" \
+-X POST \
+-F "username=king.arthur@camelot.bt" \
+-F "password=guinevere" \
+http://localhost:9000/users/login/cookie
+const formData = new FormData();
+formData.set('username', 'king.arthur@camelot.bt');
+formData.set('password', 'guinevere');
+axios.post(
+ 'http://localhost:9000/users/login/cookie',
+ 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 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:9000/users/me
+const TOKEN = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiNGZkMzQ3N2ItZWNjZi00ZWUzLThmN2QtNjhhZDcyMjYxNDc2IiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTg3ODE4NDI5fQ.anO3JR8-WYCozZ4_2-PQ2Ov9O38RaLP2RAzQIiZhteM';
+axios.get(
+ 'http://localhost:9000/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¶
+curl \
+-H "Content-Type: application/json" \
+-H "Authorization: Bearer $TOKEN" \
+-X PATCH \
+-d "{\"password\": \"lancelot\"}" \
+http://localhost:9000/users/me
+axios.patch(
+ 'http://localhost:9000/users/me',
+ {
+ password: 'lancelot',
+ },
+ {
+ 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
+}
+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¶
+curl \
+-H "Content-Type: application/json" \
+-H "Authorization: Bearer $TOKEN" \
+-X GET \
+http://localhost:9000/users/4fd3477b-eccf-4ee3-8f7d-68ad72261476
+axios.get(
+ 'http://localhost:9000/users/4fd3477b-eccf-4ee3-8f7d-68ad72261476', {
+ 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
+}
+5.1. Update any user¶
+We can now update the profile of any user. For example, we can promote it as superuser.
+Request¶
+curl \
+-H "Content-Type: application/json" \
+-H "Authorization: Bearer $TOKEN" \
+-X PATCH \
+ -d "{\"is_superuser\": true}" \
+http://localhost:9000/users/4fd3477b-eccf-4ee3-8f7d-68ad72261476
+axios.patch(
+ 'http://localhost:9000/users/4fd3477b-eccf-4ee3-8f7d-68ad72261476',
+ {
+ is_superuser: true,
+ },
+ {
+ 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": true
+}
+5.2. Delete any user¶
+Finally, we can delete a user.
+Request¶
+curl \
+-H "Content-Type: application/json" \
+-H "Authorization: Bearer $TOKEN" \
+-X DELETE \
+http://localhost:9000/users/4fd3477b-eccf-4ee3-8f7d-68ad72261476
+axios.delete(
+ 'http://localhost:9000/users/4fd3477b-eccf-4ee3-8f7d-68ad72261476',
+ {
+ headers: {
+ 'Authorization': `Bearer ${TOKEN}`,
+ },
+ },
+)
+.then((response) => console.log(response))
+.catch((error) => console.log(error));
+Response¶
+You'll get an empty response.
+6. Logout¶
+We can also end the session. Note that it doesn't apply to every authentication backends. For JWT, it doesn't make sense to end the session, the token is valid until it expires. However, for Cookie backend, the server will clear the cookie.
+Request¶
+curl \
+-H "Content-Type: application/json" \
+-H "Authorization: Bearer $TOKEN" \
+-X POST \
+http://localhost:9000/users/logout/cookie
+axios.post('http://localhost:9000/users/logout/cookie',
+ null,
+ {
+ headers: {
+ 'Authorization': `Bearer ${TOKEN}`,
+ },
+ }
+)
+.then((response) => console.log(response))
+.catch((error) => console.log(error));
+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.
+ + + + + + + +