88b133d41c
* Move users router in sub-module * Factorize UserRouter into EventHandlersRouter * Implement OAuth registration/login router * Apply isort/black * Remove temporary pytest marker * Fix httpx-oauth version in lock file * Ensure ON_AFTER_REGISTER event is triggered on OAuth registration * Add API on FastAPIUsers to generate an OAuth router * Improve test coverage of FastAPIUsers * Small fixes * Write the OAuth documentation * Fix SQL unit-tests by avoiding collisions in SQLite db files
6.8 KiB
Routes
You'll find here the routes exposed by FastAPI Users. Note that you can also review them through the interactive API docs.
Unauthenticated
POST /register
Register a new user. Will call the on_after_register event handlers 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"
}
```
POST /login/{name}
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 /forgot-password
Request a reset password procedure. Will generate a temporary token and call the on_after_forgot_password event 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 routes
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.
Authenticated
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.
Superuser
GET /
Return the list of registered users.
!!! 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.
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.