Skip to content
You're not viewing the latest version. Click here to go to latest.

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

Payload (`application/x-www-form-urlencoded`)

    username=king.arthur@camelot.bt&password=guinevere

`422 Validation Error`

`400 Bad Request`

Bad credentials or the user is inactive.

    {
        "detail": "LOGIN_BAD_CREDENTIALS"
    }

`400 Bad Request`

The user is not verified.

    {
        "detail": "LOGIN_USER_NOT_VERIFIED"
    }

### `POST /logout`

Logout the authenticated user against the method named `name`. Check the corresponding authentication method to view the success response.

`401 Unauthorized`

Missing token or inactive user.

`200 OK`

The logout process was successful.

## Register router

### `POST /register`

Register a new user. Will call the `on_after_register` handler on successful registration.

Payload

    {
        "email": "king.arthur@camelot.bt",
        "password": "guinevere"
    }

`201 Created`

    {
        "id": "57cbb51a-ab71-4009-8802-3f54b4f2e23",
        "email": "king.arthur@camelot.bt",
        "is_active": true,
        "is_superuser": false
    }

`422 Validation Error`

`400 Bad Request`

A user already exists with this email.

    {
        "detail": "REGISTER_USER_ALREADY_EXISTS"
    }

`400 Bad Request`

Password validation failed.

    {
        "detail": {
            "code": "REGISTER_INVALID_PASSWORD",
            "reason": "Password should be at least 3 characters"
        }
    }

## Reset password router

### `POST /forgot-password`

Request a reset password procedure. Will generate a temporary token and call the `on_after_forgot_password` handler if the user exists.

To prevent malicious users from guessing existing users in your database, the route will always return a `202 Accepted` response, even if the user requested does not exist.

Payload

    {
        "email": "king.arthur@camelot.bt"
    }

`202 Accepted`

### `POST /reset-password`

Reset a password. Requires the token generated by the `/forgot-password` route.

Payload

    {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiOTIyMWZmYzktNjQwZi00MzcyLTg2ZDMtY2U2NDJjYmE1NjAzIiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTcxNTA0MTkzfQ.M10bjOe45I5Ncu_uXvOmVV8QxnL-nZfcH96U90JaocI",
        "password": "merlin"
    }

`200 OK`

`422 Validation Error`

`400 Bad Request`

Bad or expired token.

    {
        "detail": "RESET_PASSWORD_BAD_TOKEN"
    }

`400 Bad Request`

Password validation failed.

    {
        "detail": {
            "code": "REGISTER_INVALID_PASSWORD",
            "reason": "Password should be at least 3 characters"
        }
    }

## Verify router

### `POST /request-verify-token`

Request a user to verify their e-mail. Will generate a temporary token and call the `on_after_request_verify` handler if the user exists, active and not already verified.

To prevent malicious users from guessing existing users in your database, the route will always return a `202 Accepted` response, even if the user requested does not exist, not active or already verified.

Payload

    {
        "email": "king.arthur@camelot.bt"
    }

`202 Accepted`

### `POST /verify`

Verify a user. Requires the token generated by the `/request-verify-token` route. Will call the call the `on_after_verify` handler on success.

Payload

    {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiOTIyMWZmYzktNjQwZi00MzcyLTg2ZDMtY2U2NDJjYmE1NjAzIiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTcxNTA0MTkzfQ.M10bjOe45I5Ncu_uXvOmVV8QxnL-nZfcH96U90JaocI"
    }

`200 OK`

`422 Validation Error`

`400 Bad Request`

Bad token, not existing user or not the e-mail currently set for the user.

    {
        "detail": "VERIFY_USER_BAD_TOKEN"
    }

`400 Bad Request`

The user is already verified.

    {
        "detail": "VERIFY_USER_ALREADY_VERIFIED"
    }

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

Query parameters

- `scopes`: Optional list of scopes to ask for. Expected format: `scopes=a&scopes=b`.

`200 OK`

    {
        "authorization_url": "https://www.tintagel.bt/oauth/authorize?client_id=CLIENT_ID&scopes=a+b&redirect_uri=https://www.camelot.bt/oauth/callback"
    }

`422 Validation Error`

Invalid parameters - e.g. unknown authentication backend.

### `GET /callback`

Handle the OAuth callback.

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.

`400 Bad Request`

Invalid token.

`400 Bad Request`

User is inactive.

    {
        "detail": "LOGIN_BAD_CREDENTIALS"
    }

## Users router

### `GET /me`

Return the current authenticated active user.

`200 OK`

    {
        "id": "57cbb51a-ab71-4009-8802-3f54b4f2e23",
        "email": "king.arthur@camelot.bt",
        "is_active": true,
        "is_superuser": false
    }

`401 Unauthorized`

Missing token or inactive user.

### `PATCH /me`

Update the current authenticated active user.

Payload

    {
        "email": "king.arthur@tintagel.bt",
        "password": "merlin"
    }

`200 OK`

    {
        "id": "57cbb51a-ab71-4009-8802-3f54b4f2e23",
        "email": "king.arthur@tintagel.bt",
        "is_active": true,
        "is_superuser": false
    }

`401 Unauthorized`

Missing token or inactive user.

`400 Bad Request`

Password validation failed.

    {
        "detail": {
            "code": "UPDATE_USER_INVALID_PASSWORD",
            "reason": "Password should be at least 3 characters"
        }
    }

`400 Bad Request`

A user with this email already exists.

    {
        "detail": "UPDATE_USER_EMAIL_ALREADY_EXISTS"
    }

`422 Validation Error`

### `GET /{user_id}`

Return the user with id `user_id`.

`200 OK`

    {
        "id": "57cbb51a-ab71-4009-8802-3f54b4f2e23",
        "email": "king.arthur@camelot.bt",
        "is_active": true,
        "is_superuser": false
    }

`401 Unauthorized`

Missing token or inactive user.

`403 Forbidden`

Not a superuser.

`404 Not found`

The user does not exist.

### `PATCH /{user_id}`

Update the user with id `user_id`.

Payload

    {
        "email": "king.arthur@tintagel.bt",
        "password": "merlin",
        "is_active": false,
        "is_superuser": true
    }

`200 OK`

    {
        "id": "57cbb51a-ab71-4009-8802-3f54b4f2e23",
        "email": "king.arthur@camelot.bt",
        "is_active": false,
        "is_superuser": true
    }

`401 Unauthorized`

Missing token or inactive user.

`403 Forbidden`

Not a superuser.

`404 Not found`

The user does not exist.

`400 Bad Request`

Password validation failed.

    {
        "detail": {
            "code": "UPDATE_USER_INVALID_PASSWORD",
            "reason": "Password should be at least 3 characters"
        }
    }

`400 Bad Request`

A user with this email already exists.

    {
        "detail": "UPDATE_USER_EMAIL_ALREADY_EXISTS"
    }

### `DELETE /{user_id}`

Delete the user with id `user_id`.

`204 No content`

`401 Unauthorized`

Missing token or inactive user.

`403 Forbidden`

Not a superuser.

`404 Not found`

The user does not exist.

Back to top