Authentication

Overview

SpendWisely George uses Fold Money’s OTP-based authentication system. The authentication flow involves requesting an OTP via SMS, verifying the OTP, and storing the resulting access and refresh tokens locally.

Authentication Flow

Request OTP

Send the user’s phone number to initiate OTP delivery

Verify OTP

Submit the received OTP code for verification

Token Storage

Access and refresh tokens are automatically saved to unfold_config.yaml

Request OTP

This endpoint triggers Fold Money to send an OTP via SMS to the provided phone number.

Initiates the OTP authentication flow

Request Body

phone

string

required

Phone number in format +91XXXXXXXXXX or XXXXXXXXXX (will auto-prefix +91)

Example Request

curl -X POST http://localhost:8000/api/fold/login \
  -H "Content-Type: application/json" \
  -d '{"phone": "9876543210"}'

Response

status

string

Always returns "otp_sent" on success

{
  "status": "otp_sent"
}

Error Response

{
  "detail": "Connection error or API failure message"
}

detail

string

Error message when OTP request fails (400 status code)

Verify OTP

/api/fold/verify

POST

Verifies the OTP and stores authentication tokens

Request Body

phone

string

required

Same phone number used in the login request

otp

string

required

6-digit OTP code received via SMS

Example Request

curl -X POST http://localhost:8000/api/fold/verify \
  -H "Content-Type: application/json" \
  -d '{"phone": "9876543210", "otp": "123456"}'

Response

status

string

Returns "success" when OTP is verified and tokens are saved

{
  "status": "success"
}

Error Responses

Invalid OTP:

{
  "detail": "Verification failed: Invalid OTP"
}

Invalid Response from Fold:

{
  "detail": "Invalid response from Fold"
}

detail

string

Error message describing verification failure (400 status code)

Check Authentication Status

/api/fold/status

GET

Checks if user is currently authenticated

Example Request

curl http://localhost:8000/api/fold/status

Response

logged_in

boolean

true if valid access token exists in config, false otherwise

{
  "logged_in": true
}

Token Management

Storage Location

Tokens are stored in unfold_config.yaml in the application root:

token:
  access: "eyJhbGciOiJIUzI1NiIs..."
  refresh: "eyJhbGciOiJIUzI1NiIs..."
fold_user:
  uuid: "user-uuid-here"
device_hash: "python-client-a1b2c3d4"

Token Format

access_token

string

JWT token used for authenticating requests to Fold Money API

refresh_token

string

JWT token used to obtain new access tokens when they expire

uuid

string

Unique user identifier from Fold Money

Device Hash

A random device hash is generated during verification:

"python-client-" + os.urandom(4).hex()

Example: python-client-7f3e9a2c

Phone Number Formatting

The API automatically formats phone numbers:

"9876543210"

If the phone number already starts with +, it is used as-is.

Integration with Fold Money API

The authentication endpoints proxy requests to Fold Money:

POST https://api.fold.money/v1/auth/otp

Verify Endpoint

POST https://api.fold.money/v1/auth/otp/verify

Ensure you have network access to api.fold.money for authentication to work.

Error Handling

All authentication endpoints return HTTP 400 for failures:

Error Type	Status Code	Detail Message
Network failure	400	Connection error details
Invalid OTP	400	”Verification failed: Invalid OTP”
Missing tokens	400	”Invalid response from Fold”

Backend API

Google Apps Script

Overview

Authentication Flow

Request OTP

Request Body

Example Request

Response

Error Response

Verify OTP

Request Body

Example Request

Response

Error Responses

Check Authentication Status

Example Request

Response

Token Management

Storage Location

Token Format

Device Hash

Phone Number Formatting

Integration with Fold Money API

Verify Endpoint

Error Handling

Next Steps

Sync Transactions

View Portfolio

Build docs developers (and LLMs) love

Backend API

Google Apps Script

​Overview

​Authentication Flow

​Request OTP

​Request Body

​Example Request

​Response

​Error Response

​Verify OTP

​Request Body

​Example Request

​Response

​Error Responses

​Check Authentication Status

​Example Request

​Response

​Token Management

​Storage Location

​Token Format

​Device Hash

​Phone Number Formatting

​Integration with Fold Money API

​Login Endpoint

​Verify Endpoint

​Error Handling

​Next Steps

Sync Transactions

View Portfolio

Build docs developers (and LLMs) love

Overview

Authentication Flow

Request OTP

Request Body

Example Request

Response

Error Response

Verify OTP

Request Body

Example Request

Response

Error Responses

Check Authentication Status

Example Request

Response

Token Management

Storage Location

Token Format

Device Hash

Phone Number Formatting

Integration with Fold Money API

Login Endpoint

Verify Endpoint

Error Handling

Next Steps