Skip to main content
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

​
string
required
The user’s phone number in Uganda format. Must match the pattern +256XXXXXXXXX (country code followed by 9 digits).
​
string
required
The user’s 4-digit numeric PIN. Must be exactly 4 digits (e.g., "1234"). No letters or special characters are accepted.
​
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.
​
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

​
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.
​
string
required
The user’s display name as stored in their account.
​
string
required
The user’s role in the group. Either "admin" or "member".
​
boolean
required
true if this user created the group, false otherwise. Group creators may have elevated permissions within admin interfaces.

​
Error responses

​
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

​
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.
​
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

​
Examples

Successful response (both endpoints)
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.”