User Management

Create User

curl -X POST https://api.sfluv.org/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

{}

Creates a new user account using the authenticated user’s DID from the JWT token. POST /users Authentication: Required (Bearer token via Privy) Request Body: None (user ID is extracted from JWT)

Response

Returns 201 Created on success with no body.

Get Authenticated User

curl -X GET https://api.sfluv.org/users \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "user": {
    "id": "did:privy:user123",
    "exists": true,
    "is_admin": false,
    "is_merchant": true,
    "is_organizer": false,
    "is_improver": false,
    "is_proposer": false,
    "is_voter": true,
    "is_issuer": false,
    "is_supervisor": false,
    "is_affiliate": false,
    "contact_email": "[email protected]",
    "contact_phone": "+1234567890",
    "contact_name": "John Doe",
    "paypal_eth": "0x...",
    "last_redemption": 1678901234
  },
  "wallets": [
    {
      "id": 1,
      "owner": "did:privy:user123",
      "name": "My Wallet",
      "is_eoa": true,
      "is_redeemer": false,
      "is_minter": false,
      "eoa_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "smart_address": null,
      "smart_index": null,
      "last_unwrap_at": null
    }
  ],
  "locations": [],
  "contacts": [],
  "affiliate": null,
  "proposer": null,
  "improver": null,
  "issuer": null,
  "supervisor": null
}

Retrieves the authenticated user’s complete profile including associated wallets, locations, contacts, and role information. GET /users Authentication: Required (Bearer token via Privy)

Response Fields

user

object

required

User profile information

Show User object properties

string

required

User’s decentralized identifier (DID)

exists

boolean

required

Whether the user record exists in the database

is_admin

boolean

required

Admin role flag

is_merchant

boolean

required

Merchant role flag

is_organizer

boolean

required

Organizer role flag

is_improver

boolean

required

Improver role flag (community project worker)

is_proposer

boolean

required

Proposer role flag (can create workflow proposals)

is_voter

boolean

required

Voter role flag (can vote on workflows)

is_issuer

boolean

required

Issuer role flag (can issue credentials)

is_supervisor

boolean

required

Supervisor role flag

is_affiliate

boolean

required

Affiliate role flag

contact_email

string | null

User’s contact email address

contact_phone

string | null

User’s contact phone number

contact_name

string | null

User’s display name

paypal_eth

string

User’s PayPal ETH address for payouts

last_redemption

integer

Timestamp of last code redemption

wallets

array

required

Array of wallet objects associated with the user

locations

array

required

Array of merchant location objects

contacts

array

required

Array of contact objects

affiliate

object | null

Affiliate information if user has affiliate role

proposer

object | null

Proposer information if user has proposer role

improver

object | null

Improver information if user has improver role

issuer

object | null

Issuer information if user has issuer role

supervisor

object | null

Supervisor information if user has supervisor role

Update User Information

curl -X PUT https://api.sfluv.org/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "[email protected]",
    "contact_phone": "+1234567890",
    "contact_name": "Jane Smith"
  }'

{}

Updates the authenticated user’s profile information. PUT /users Authentication: Required (Bearer token via Privy)

Request Body

contact_email

string

User’s email address

contact_phone

string

User’s phone number

contact_name

string

User’s display name

Response

Returns 201 Created on success with no body.

Update PayPal ETH Address

curl -X PUT https://api.sfluv.org/paypaleth \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: text/plain" \
  -d '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'

{}

Updates the user’s PayPal ETH address for receiving payouts. PUT /paypaleth Authentication: Required (Bearer token via Privy)

Request Body

Raw Ethereum address string (Content-Type: text/plain)

Get Verified Emails

curl -X GET https://api.sfluv.org/users/verified-emails \
  -H "Authorization: Bearer YOUR_TOKEN"

[
  {
    "id": "email_abc123",
    "user_id": "did:privy:user123",
    "email": "[email protected]",
    "status": "verified",
    "verified_at": "2024-03-15T10:30:00Z",
    "verification_sent_at": "2024-03-15T10:00:00Z",
    "verification_token_expires_at": null,
    "created_at": "2024-03-15T10:00:00Z",
    "updated_at": "2024-03-15T10:30:00Z"
  },
  {
    "id": "email_def456",
    "user_id": "did:privy:user123",
    "email": "[email protected]",
    "status": "pending",
    "verified_at": null,
    "verification_sent_at": "2024-03-16T14:20:00Z",
    "verification_token_expires_at": "2024-03-16T14:50:00Z",
    "created_at": "2024-03-16T14:20:00Z",
    "updated_at": "2024-03-16T14:20:00Z"
  }
]

Retrieves all verified and pending email addresses for the authenticated user. GET /users/verified-emails Authentication: Required (Bearer token via Privy)

Response Fields

string

required

Unique identifier for the email record

user_id

string

required

User’s DID

string

required

Email address

status

string

required

Verification status: verified, pending, or expired

verified_at

string | null

ISO 8601 timestamp when email was verified

verification_sent_at

string | null

ISO 8601 timestamp when verification email was sent

verification_token_expires_at

string | null

ISO 8601 timestamp when verification token expires (typically 30 minutes)

created_at

string

required

ISO 8601 timestamp of record creation

updated_at

string

required

ISO 8601 timestamp of last update

Request Email Verification

curl -X POST https://api.sfluv.org/users/verified-emails \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

{
  "id": "email_abc123",
  "user_id": "did:privy:user123",
  "email": "[email protected]",
  "status": "pending",
  "verified_at": null,
  "verification_sent_at": "2024-03-15T10:00:00Z",
  "verification_token_expires_at": "2024-03-15T10:30:00Z",
  "created_at": "2024-03-15T10:00:00Z",
  "updated_at": "2024-03-15T10:00:00Z"
}

Initiates email verification by creating a verification record and sending a verification email with a token. POST /users/verified-emails Authentication: Required (Bearer token via Privy)

Request Body

string

required

Email address to verify

Response

Returns the created email verification record with pending status. A verification email is sent to the provided address containing a link with a verification token that expires in 30 minutes.

Resend Email Verification

curl -X POST https://api.sfluv.org/users/verified-emails/email_abc123/resend \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "id": "email_abc123",
  "user_id": "did:privy:user123",
  "email": "[email protected]",
  "status": "pending",
  "verified_at": null,
  "verification_sent_at": "2024-03-15T10:45:00Z",
  "verification_token_expires_at": "2024-03-15T11:15:00Z",
  "created_at": "2024-03-15T10:00:00Z",
  "updated_at": "2024-03-15T10:45:00Z"
}

Resends the verification email for a pending email verification record. POST /users/verified-emails/{email_id}/resend Authentication: Required (Bearer token via Privy)

Path Parameters

email_id

string

required

The ID of the email verification record

Response

Returns the updated email verification record with new verification_sent_at and verification_token_expires_at timestamps. A new verification email is sent.

Verify Email Token

curl -X POST https://api.sfluv.org/users/verified-emails/verify?token=abc123xyz \
  -H "Content-Type: application/json"

{
  "id": "email_abc123",
  "user_id": "did:privy:user123",
  "email": "[email protected]",
  "status": "verified",
  "verified_at": "2024-03-15T10:15:00Z",
  "verification_sent_at": "2024-03-15T10:00:00Z",
  "verification_token_expires_at": null,
  "created_at": "2024-03-15T10:00:00Z",
  "updated_at": "2024-03-15T10:15:00Z"
}

Verifies an email address using the token from the verification email. POST /users/verified-emails/verify Authentication: Not required (public endpoint)

Request Parameters

Token can be provided via query parameter OR request body (query parameter takes precedence):

token

string

Verification token from email link

token

string

Verification token (if not provided as query parameter)

Response

Returns the updated email verification record with verified status and verified_at timestamp.

Error Responses

All endpoints may return the following error responses:

400 Bad Request

Invalid request format or parameters

403 Forbidden

Missing or invalid authentication token

404 Not Found

Requested resource not found

409 Conflict

Resource conflict (e.g., email already verified)

410 Gone

Resource has expired (e.g., verification token)

500 Internal Server Error

Server-side error occurred

Overview

User Management

Workflows

Roles & Credentials

Locations

Affiliates

Compliance

Blockchain Integration

User Management

Create User

Response

Get Authenticated User

Response Fields

Update User Information

Request Body

Response

Update PayPal ETH Address

Request Body

Get Verified Emails

Response Fields

Request Email Verification

Request Body

Response

Resend Email Verification

Path Parameters

Response

Verify Email Token

Request Parameters

Response

Error Responses

Build docs developers (and LLMs) love

Overview

User Management

Workflows

Roles & Credentials

Locations

Affiliates

Compliance

Blockchain Integration

​Create User

​Response

​Get Authenticated User

​Response Fields

​Update User Information

​Request Body

​Response

​Update PayPal ETH Address

​Request Body

​Get Verified Emails

​Response Fields

​Request Email Verification

​Request Body

​Response

​Resend Email Verification

​Path Parameters

​Response

​Verify Email Token

​Request Parameters

​Response

​Error Responses

Build docs developers (and LLMs) love

Create User

Response

Get Authenticated User

Response Fields

Update User Information

Request Body

Response

Update PayPal ETH Address

Request Body

Get Verified Emails

Response Fields

Request Email Verification

Request Body

Response

Resend Email Verification

Path Parameters

Response

Verify Email Token

Request Parameters

Response

Error Responses