Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.digiflecttech.dev/llms.txt

Use this file to discover all available pages before exploring further.

The Save App authentication API supports two login methods: a phone number and PIN combination for standard accounts, and a Firebase ID token for accounts verified through Google’s phone authentication service. Both methods return a JWT bearer token valid for 24 hours that you include in all subsequent authenticated requests.

​
POST /api/auth/login

Authenticates a user with a phone number and 4-digit PIN. Optionally accepts a groupName to prevent cross-group access and a loginType to restrict portal access by role.

​
Request body

​
phone
string
required
The user’s phone number in Uganda format. Must match the pattern +256XXXXXXXXX (country code followed by 9 digits).
​
password
string
required
The user’s 4-digit numeric PIN. Must be exactly 4 digits (e.g., "1234"). No letters or special characters are accepted.
​
groupName
string
The name of the group to log into. When provided, the server verifies that the user belongs to this group. Use this to prevent a user from one group accidentally or maliciously accessing another group’s portal.
​
loginType
string
Restricts login to a specific portal type. Accepted values are "admin" or "member". Passing "admin" blocks non-admin users from reaching the admin portal.

​
Response

​
token
string
required
A signed JWT bearer token. Include this value in the Authorization header as Bearer <token> on all subsequent authenticated requests. The token is valid for 24 hours.
​
name
string
required
The user’s display name as stored in their account.
​
role
string
required
The user’s role in the group. Either "admin" or "member".
​
is_creator
boolean
required
true if this user created the group, false otherwise. Group creators may have elevated permissions within admin interfaces.

​
Error responses

StatusCondition
401 UnauthorizedPhone number not found, password does not match, or the account uses Google sign-in and cannot accept a PIN.
403 ForbiddenAccount is inactive, the user belongs to a different group than groupName, or a non-admin attempted to log in with loginType: "admin".

​
POST /api/auth/firebase-login

Authenticates a user using a Firebase ID token obtained from Firebase Phone Authentication on the client. If the phone number in the decoded token does not yet have an account in the specified group, a new member account is created automatically.
This endpoint is rate-limited to 10 requests per minute. Implement exponential back-off on your client when retrying after a 429 response.

​
Request body

​
idToken
string
required
The Firebase ID token issued by Firebase Authentication after the client completes phone verification. Obtain this token client-side using the Firebase SDK.
​
group_name
string
required
The name of the group the user is logging into. Must be between 2 and 100 characters. If the phone number is new, the account is created under this group.

​
Response

Returns the same LoginResponse shape as POST /api/auth/login.

​
Error responses

StatusCondition
400 Bad RequestThe Firebase token does not contain a phone number.
401 UnauthorizedThe Firebase ID token is invalid or expired.
403 ForbiddenThe phone number is already registered under a different group than group_name, or the account is inactive.

​
Examples

curl --request POST \
  --url https://api.saveapp.co/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "phone": "+256700123456",
    "password": "1234",
    "groupName": "Kampala Savers",
    "loginType": "member"
  }'
Successful response (both endpoints) 
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "name": "Aisha Nakato",
  "role": "member",
  "is_creator": false
}
Accounts managed by Firebase (i.e., created via firebase-login) cannot be used with the phone/PIN login endpoint. Attempting to do so returns 401 Unauthorized with the message “This account is managed by Google. Please sign in with Google.”