7721f8dcc1
* Fix #68: use makefun to generate dynamic dependencies * Remove every Starlette imports * Split every routers and remove event handlers * Make users router optional * Pass after_update handler to get_users_router * Update documentation * Remove test file * Write migration doc for splitted routers
7.1 KiB
Routes
You'll find here the routes exposed by FastAPI Users. Note that you can also review them through the interactive API docs.
Auth router
Each authentication backend you generate a router for will produce the following routes. Take care about the prefix you gave it, especially if you have several backends.
POST /login
Login a user against the method named name. Check the corresponding authentication method to view the success response.
!!! abstract "Payload (application/x-www-form-urlencoded)"
username=king.arthur@camelot.bt&password=guinevere
!!! fail "422 Validation Error"
!!! fail "400 Bad Request"
Bad credentials or the user is inactive.
```json
{
"detail": "LOGIN_BAD_CREDENTIALS"
}
```
POST /logout
Logout the authenticated user against the method named name. Check the corresponding authentication method to view the success response.
!!! fail "401 Unauthorized"
Missing token or inactive user.
!!! success "200 OK"
The logout process was successful.
!!! tip Some backend (like JWT) won't produce this route.
Register router
POST /register
Register a new user. Will call the after_register handler on successful registration.
!!! abstract "Payload"
json { "email": "king.arthur@camelot.bt", "password": "guinevere" }
!!! success "201 Created"
json { "id": "57cbb51a-ab71-4009-8802-3f54b4f2e23", "email": "king.arthur@camelot.bt", "is_active": true, "is_superuser": false }
!!! fail "422 Validation Error"
!!! fail "400 Bad Request"
A user already exists with this email.
```json
{
"detail": "REGISTER_USER_ALREADY_EXISTS"
}
```
Reset password router
POST /forgot-password
Request a reset password procedure. Will generate a temporary token and call the after_forgot_password handlers if the user exists.
To prevent malicious users from guessing existing users in your databse, the route will always return a 202 Accepted response, even if the user requested does not exist.
!!! abstract "Payload"
json { "email": "king.arthur@camelot.bt" }
!!! success "202 Accepted"
POST /reset-password
Reset a password. Requires the token generated by the /forgot-password route.
!!! abstract "Payload"
json { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiOTIyMWZmYzktNjQwZi00MzcyLTg2ZDMtY2U2NDJjYmE1NjAzIiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTcxNTA0MTkzfQ.M10bjOe45I5Ncu_uXvOmVV8QxnL-nZfcH96U90JaocI", "password": "merlin" }
!!! success "200 OK"
!!! fail "422 Validation Error"
!!! fail "400 Bad Request"
Bad or expired token.
```json
{
"detail": "RESET_PASSWORD_BAD_TOKEN"
}
```
OAuth router
Each OAuth router you define will expose the two following routes.
GET /authorize
Return the authorization URL for the OAuth service where you should redirect your user.
!!! abstract "Query parameters"
* authentication_backend: Name of a defined authentication method to use to authenticate the user on successful callback.
* scopes: Optional list of scopes to ask for. Expected format: scopes=a&scopes=b.
!!! success "200 OK"
json { "authorization_url": "https://www.tintagel.bt/oauth/authorize?client_id=CLIENT_ID&scopes=a+b&redirect_uri=https://www.camelot.bt/oauth/callback" }
!!! fail "422 Validation Error"
!!! fail "400 Bad Request"
Unknown authentication backend.
GET /callback
Handle the OAuth callback.
!!! abstract "Query parameters"
* code: OAuth callback code.
* state: State token.
* error: OAuth error.
Depending on the situation, several things can happen:
- The OAuth account exists in database and is linked to a user:
- OAuth account is updated in database with fresh access token.
- The user is authenticated following the chosen authentication method.
- The OAuth account doesn't exist in database but a user with the same email address exists:
- OAuth account is linked to the user.
- The user is authenticated following the chosen authentication method.
- The OAuth account doesn't exist in database and no user with the email address exists:
- A new user is created and linked to the OAuth account.
- The user is authenticated following the chosen authentication method.
Users router
GET /me
Return the current authenticated active user.
!!! success "200 OK"
json { "id": "57cbb51a-ab71-4009-8802-3f54b4f2e23", "email": "king.arthur@camelot.bt", "is_active": true, "is_superuser": false }
!!! fail "401 Unauthorized"
Missing token or inactive user.
PATCH /me
Update the current authenticated active user.
!!! abstract "Payload"
json { "email": "king.arthur@tintagel.bt", "password": "merlin" }
!!! success "200 OK"
json { "id": "57cbb51a-ab71-4009-8802-3f54b4f2e23", "email": "king.arthur@tintagel.bt", "is_active": true, "is_superuser": false }
!!! fail "401 Unauthorized"
Missing token or inactive user.
GET /{user_id}
Return the user with id user_id.
!!! success "200 OK"
json { "id": "57cbb51a-ab71-4009-8802-3f54b4f2e23", "email": "king.arthur@camelot.bt", "is_active": true, "is_superuser": false }
!!! fail "401 Unauthorized"
Missing token or inactive user.
!!! fail "403 Forbidden"
Not a superuser.
!!! fail "404 Not found"
The user does not exist.
PATCH /{user_id}
Update the user with id user_id.
!!! abstract "Payload"
json { "email": "king.arthur@tintagel.bt", "password": "merlin", "is_active": false, "is_superuser": true }
!!! success "200 OK"
json { "id": "57cbb51a-ab71-4009-8802-3f54b4f2e23", "email": "king.arthur@camelot.bt", "is_active": false, "is_superuser": true }
!!! fail "401 Unauthorized"
Missing token or inactive user.
!!! fail "403 Forbidden"
Not a superuser.
!!! fail "404 Not found"
The user does not exist.
DELETE /{user_id}
Delete the user with id user_id.
!!! success "204 No content"
!!! fail "401 Unauthorized"
Missing token or inactive user.
!!! fail "403 Forbidden"
Not a superuser.
!!! fail "404 Not found"
The user does not exist.