fastapi-users/docs/usage/routes.md

# Routes

You'll find here the routes exposed by **FastAPI Users**. Note that you can also review them through the [interactive API docs](https://fastapi.tiangolo.com/tutorial/first-steps/#interactive-api-docs).

## Unauthenticated

### `POST /register`

Register a new user. Will call the `on_after_register` [event handlers](../configuration/router.md#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`

Login a user.

!!! abstract "Payload (`application/x-www-form-urlencoded`)"
    ```
    username=king.arthur@camelot.bt&password=guinevere
    ```

!!! success "`200 OK`"
    ```json
    {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiOTIyMWZmYzktNjQwZi00MzcyLTg2ZDMtY2U2NDJjYmE1NjAzIiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTcxNTA0MTkzfQ.M10bjOe45I5Ncu_uXvOmVV8QxnL-nZfcH96U90JaocI"
    }
    ```

!!! 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](../configuration/router.md#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"
    }
    ```

## 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.