Authentication endpoints: register, login, OAuth

The auth API handles the complete identity lifecycle: account creation, credential-based login, JWT token management, email verification, password recovery, and OAuth sign-in via Google or GitHub. All endpoints are mounted under the /api/auth/ prefix.

POST /api/auth/register

Create a new user account. After registration, a verification email is sent to the provided address.

string

required

The user’s email address. Must be a valid email format and not already registered.

string

required

The user’s password in plain text. It is hashed before storage.

string

The user’s display name. Optional.

curl --request POST \
  --url http://localhost:8000/api/auth/register \
  --header "Content-Type: application/json" \
  --data '{
    "email": "user@example.com",
    "password": "secure-password-123",
    "full_name": "Jane Smith"
  }'

import requests

response = requests.post(
    "http://localhost:8000/api/auth/register",
    json={
        "email": "user@example.com",
        "password": "secure-password-123",
        "full_name": "Jane Smith",
    },
)
print(response.json())

Response — UserResponse:

string

required

UUID of the newly created user.

string

required

The registered email address.

string

The user’s display name, if provided.

string

Profile picture URL. null for newly registered users.

boolean

required

Whether the account is active. true by default on registration.

boolean

required

Whether the email has been verified. false until the verification link is clicked.

string

The OAuth provider used to sign in (google, github), or null for password-based accounts.

string

required

Current subscription status (e.g., free, active, cancelled).

string

required

Subscription tier (e.g., free, pro).

string

required

ISO 8601 timestamp of when the account was created.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "user@example.com",
  "full_name": "Jane Smith",
  "avatar_url": null,
  "is_active": true,
  "is_verified": false,
  "oauth_provider": null,
  "subscription_status": "free",
  "subscription_tier": "free",
  "created_at": "2024-01-15T10:30:00Z"
}

Authenticate with email and password. Returns a JWT access token and refresh token.

string

required

The user’s registered email address.

string

required

The user’s password.

curl --request POST \
  --url http://localhost:8000/api/auth/login \
  --header "Content-Type: application/json" \
  --data '{
    "email": "user@example.com",
    "password": "secure-password-123"
  }'

import requests

response = requests.post(
    "http://localhost:8000/api/auth/login",
    json={"email": "user@example.com", "password": "secure-password-123"},
)
data = response.json()

Response — Token:

string

required

JWT access token. Valid for 30 minutes. Pass this in the Authorization header.

string

required

JWT refresh token. Use this to obtain a new access token after expiry.

string

required

Always "bearer".

object

The authenticated user object. See UserResponse fields above.

Show user properties

string

UUID of the user.

string

User’s email address.

string

User’s display name.

boolean

Email verification status.

string

Current subscription status.

string

Current subscription tier.

string

Account creation timestamp.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "user@example.com",
    "full_name": "Jane Smith",
    "is_verified": true,
    "subscription_status": "active",
    "subscription_tier": "pro",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

POST /api/auth/refresh

Exchange a valid refresh token for a new access token and refresh token pair. Both tokens are rotated on every call.

string

required

A valid, unexpired refresh token previously issued by /api/auth/login or a prior /api/auth/refresh call.

curl --request POST \
  --url http://localhost:8000/api/auth/refresh \
  --header "Content-Type: application/json" \
  --data '{"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'

Response — Token (same shape as login, user field is null):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": null
}

POST /api/auth/logout

Log out the current user. Because JWTs are stateless, the server does not invalidate the token — the client is responsible for discarding both tokens from storage. No request body required.

curl --request POST \
  --url http://localhost:8000/api/auth/logout

Response:

{
  "message": "Successfully logged out"
}

GET /api/auth/me

Return the profile of the currently authenticated user. Headers:

string

required

Bearer <access_token>

curl --request GET \
  --url http://localhost:8000/api/auth/me \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response — UserResponse (see fields above):

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "user@example.com",
  "full_name": "Jane Smith",
  "avatar_url": null,
  "is_active": true,
  "is_verified": true,
  "oauth_provider": null,
  "subscription_status": "active",
  "subscription_tier": "pro",
  "created_at": "2024-01-15T10:30:00Z"
}

POST /api/auth/verify-email

Verify a user’s email address using the token sent to them after registration.

string

required

The verification token extracted from the link in the verification email.

curl --request POST \
  --url http://localhost:8000/api/auth/verify-email \
  --header "Content-Type: application/json" \
  --data '{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'

Response:

{
  "message": "Email verified successfully"
}

If the email was already verified, the response is:

{
  "message": "Email already verified"
}

POST /api/auth/resend-verification

Resend the verification email to a registered address. This endpoint always returns 200 regardless of whether the email is registered, to prevent email enumeration.

string

required

The email address to resend the verification link to.

curl --request POST \
  --url http://localhost:8000/api/auth/resend-verification \
  --header "Content-Type: application/json" \
  --data '{"email": "user@example.com"}'

Response:

{
  "message": "If your email is registered, a verification link has been sent"
}

POST /api/auth/forgot-password

Request a password reset email. Like resend-verification, this always returns 200 to prevent email enumeration.

string

required

The email address associated with the account.

curl --request POST \
  --url http://localhost:8000/api/auth/forgot-password \
  --header "Content-Type: application/json" \
  --data '{"email": "user@example.com"}'

Response:

{
  "message": "If your email is registered, a password reset link has been sent"
}

POST /api/auth/verify-reset-token

Check whether a password reset token is still valid before presenting the reset form to the user.

string

required

The password reset token from the reset email link.

curl --request POST \
  --url http://localhost:8000/api/auth/verify-reset-token \
  --header "Content-Type: application/json" \
  --data '{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'

Response:

{
  "valid": true
}

Returns 400 with {"detail": "Invalid or expired reset token"} if the token is invalid or expired.

POST /api/auth/reset-password

Set a new password using a valid password reset token.

string

required

The password reset token from the reset email link.

string

required

The new password to set for the account.

curl --request POST \
  --url http://localhost:8000/api/auth/reset-password \
  --header "Content-Type: application/json" \
  --data '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "new_password": "new-secure-password-456"
  }'

Response:

{
  "message": "Password reset successfully"
}

GET /api/auth/oauth/

Initiate an OAuth sign-in flow. Returns the authorization URL that you redirect the user to. Supported providers are google and github.

string

required

The OAuth provider to use. Must be google or github. The provider must be configured in your backend settings.

curl --request GET \
  --url http://localhost:8000/api/auth/oauth/google

Response:

string

required

The full URL to redirect the user to in order to begin the OAuth flow.

string

required

A CSRF state token. Pass this back when handling the OAuth callback to validate the flow.

{
  "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&state=...",
  "state": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

After the user authorizes the app, the provider redirects to GET /api/auth/callback/{provider}, which exchanges the code for tokens and redirects the browser to {FRONTEND_URL}/auth/callback?access_token=...&refresh_token=....

The callback endpoint is handled automatically by the backend — you do not need to call it directly. Configure your OAuth app’s redirect URI to point to {your-backend-url}/api/auth/callback/{provider}.

Overview

Endpoints

Authentication endpoints: register, login, OAuth

POST /api/auth/register

POST /api/auth/refresh

POST /api/auth/logout

GET /api/auth/me

POST /api/auth/verify-email

POST /api/auth/resend-verification

POST /api/auth/forgot-password

POST /api/auth/verify-reset-token

POST /api/auth/reset-password

GET /api/auth/oauth/

​POST /api/auth/register

​POST /api/auth/login

​POST /api/auth/refresh

​POST /api/auth/logout

​GET /api/auth/me

​POST /api/auth/verify-email

​POST /api/auth/resend-verification

​POST /api/auth/forgot-password

​POST /api/auth/verify-reset-token

​POST /api/auth/reset-password

​GET /api/auth/oauth/

POST /api/auth/register

POST /api/auth/login

POST /api/auth/refresh

POST /api/auth/logout

GET /api/auth/me

POST /api/auth/verify-email

POST /api/auth/resend-verification

POST /api/auth/forgot-password

POST /api/auth/verify-reset-token

POST /api/auth/reset-password

GET /api/auth/oauth/