Skip to content

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": "RESET_PASSWORD_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"
}

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:
  • 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

The OAuth provider didn't return an e-mail address. Make sure this provider return e-mail address through their API and you have asked for the required scope.

{
    "detail": "OAUTH_NOT_AVAILABLE_EMAIL"
}

400 Bad Request

Another user with the same e-mail address already exists.

{
    "detail": "OAUTH_USER_ALREADY_EXISTS"
}

400 Bad Request

User is inactive.

{
    "detail": "LOGIN_BAD_CREDENTIALS"
}

OAuth association router

Each OAuth association 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.

401 Unauthorized

Missing token or inactive user.

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"
}

GET /callback

Handle the OAuth callback and add the OAuth account to the current authenticated active user.

Query parameters

  • code: OAuth callback code.
  • state: State token.
  • error: OAuth error.

401 Unauthorized

Missing token or inactive user.

400 Bad Request

Invalid token.

400 Bad Request

The OAuth provider didn't return an e-mail address. Make sure this provider return e-mail address through their API and you have asked for the required scope.

{
    "detail": "OAUTH_NOT_AVAILABLE_EMAIL"
}

200 OK

{
    "id": "57cbb51a-ab71-4009-8802-3f54b4f2e23",
    "email": "king.arthur@tintagel.bt",
    "is_active": true,
    "is_superuser": false,
    "oauth_accounts": [
        {
            "id": "6c98caf5-9bc5-4c4f-8a45-a0ae0c40cd77",
            "oauth_name": "TINTAGEL",
            "access_token": "ACCESS_TOKEN",
            "expires_at": "1641040620",
            "account_id": "king_arthur_tintagel",
            "account_email": "king.arthur@tintagel.bt"
        }
    ]
}

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