Users API: manage user profiles and accounts

The Users API gives authenticated users full control over their own profile and account data. You can retrieve and update your profile, change credentials, request a GDPR-compliant data export, and permanently delete your account. All endpoints are mounted under /api/users/ and require a valid Bearer token.

All endpoints on this page require an Authorization: Bearer <access_token> header. See Authentication for how to obtain a token.

GET /api/users/me

Return the full profile of the currently authenticated user.

curl --request GET \
  --url http://localhost:8000/api/users/me \
  --header "Authorization: Bearer <access_token>"

Response — UserResponse:

string

required

UUID of the user.

string

required

The user’s email address.

string

The user’s display name.

string

URL to the user’s profile picture.

boolean

required

Whether the account is active.

boolean

required

Whether the email address has been verified.

string

The OAuth provider used to create the account (google, github), or null for password-based accounts.

string

required

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

string

required

Current subscription tier (e.g., free, pro).

string

required

ISO 8601 timestamp of account creation.

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

PATCH /api/users/me

Update the authenticated user’s profile. Only the fields you include in the request body are updated; omitted fields are left unchanged.

string

A new display name for the user.

string

A new URL for the user’s profile picture.

curl --request PATCH \
  --url http://localhost:8000/api/users/me \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "full_name": "Jane A. Smith",
    "avatar_url": "https://example.com/avatars/jane-new.png"
  }'

import requests

response = requests.patch(
    "http://localhost:8000/api/users/me",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "full_name": "Jane A. Smith",
        "avatar_url": "https://example.com/avatars/jane-new.png",
    },
)
print(response.json())

Response — UserResponse with updated fields:

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

POST /api/users/me/change-password

Change the password for the currently authenticated user. This endpoint is only available to accounts that were created with a password. OAuth-only accounts (social login only, no password set) must use the forgot-password flow to set an initial password.

string

required

The user’s existing password.

string

required

The new password to set.

curl --request POST \
  --url http://localhost:8000/api/users/me/change-password \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "current_password": "old-password-123",
    "new_password": "new-password-456"
  }'

import requests

response = requests.post(
    "http://localhost:8000/api/users/me/change-password",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "current_password": "old-password-123",
        "new_password": "new-password-456",
    },
)
print(response.json())

Response:

{
  "message": "Password changed successfully"
}

Returns 400 if the current password is incorrect, or if the account uses social login and has no password set.

POST /api/users/me/change-email

Request an email address change. The new address must not already be in use. After the change, is_verified is set to false and a new verification email is sent to the new address.

string

required

The new email address to associate with the account. Must be a valid email format.

string

required

The user’s current password to confirm the change. Required for password-based accounts.

curl --request POST \
  --url http://localhost:8000/api/users/me/change-email \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "new_email": "new-address@example.com",
    "password": "current-password-123"
  }'

Response:

{
  "message": "Verification email sent to your new address"
}

GET /api/users/me/export

Export all personal data stored for the authenticated user as a downloadable JSON file. This endpoint is provided for GDPR compliance.

curl --request GET \
  --url http://localhost:8000/api/users/me/export \
  --header "Authorization: Bearer <access_token>" \
  --output user-data-export.json

The response is a Content-Disposition: attachment JSON file with the following fields:

string

UUID of the user.

string

Email address.

string

Display name.

string

Profile picture URL.

string

OAuth provider if applicable.

boolean

Email verification status.

string

Current subscription status.

string

Current subscription tier.

string

Account creation timestamp.

string

Last profile update timestamp.

Most recent login timestamp.

string

Timestamp of when this export was generated.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "user@example.com",
  "full_name": "Jane Smith",
  "avatar_url": null,
  "oauth_provider": null,
  "is_verified": true,
  "subscription_status": "active",
  "subscription_tier": "pro",
  "created_at": "2024-01-15T10:30:00.000000",
  "updated_at": "2024-03-01T14:22:00.000000",
  "last_login_at": "2024-03-10T09:00:00.000000",
  "exported_at": "2024-03-10T09:05:00.000000"
}

DELETE /api/users/me

Permanently delete the authenticated user’s account. This action is irreversible. For password-based accounts, you must supply the current password to confirm deletion. For OAuth-only accounts (no password), you must pass "confirm": "DELETE" instead.

string

The user’s current password. Required for password-based accounts.

string

Must be the exact string "DELETE". Required for OAuth-only accounts that have no password.

Deleting an account is permanent. All user data is removed from the database immediately and cannot be recovered.

curl --request DELETE \
  --url http://localhost:8000/api/users/me \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --data '{"password": "current-password-123"}'

curl --request DELETE \
  --url http://localhost:8000/api/users/me \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --data '{"confirm": "DELETE"}'

Response:

{
  "message": "User deleted successfully"
}

Overview

Endpoints

Users API: manage user profiles and accounts

GET /api/users/me

PATCH /api/users/me

POST /api/users/me/change-password

POST /api/users/me/change-email

GET /api/users/me/export

DELETE /api/users/me

​GET /api/users/me

​PATCH /api/users/me

​POST /api/users/me/change-password

​POST /api/users/me/change-email

​GET /api/users/me/export

​DELETE /api/users/me

GET /api/users/me

PATCH /api/users/me

POST /api/users/me/change-password

POST /api/users/me/change-email

GET /api/users/me/export

DELETE /api/users/me