API Authentication: Firebase ID Tokens and Roles

The Aplauso API uses Firebase Authentication ID tokens as bearer tokens. Most endpoints require a valid token; a few guest-facing endpoints (such as creating a tip from a kiosk) are publicly accessible.

Getting a Token

From a Firebase Client SDK (frontend apps)

import { getAuth } from "firebase/auth";

const auth = getAuth();
const user = auth.currentUser;
if (user) {
  const idToken = await user.getIdToken();
  // idToken is a signed JWT string
}

Tokens expire after 1 hour. The Firebase SDK refreshes them automatically. Always call getIdToken() immediately before each request rather than caching the result.

From the Firebase Admin SDK (server-side)

import admin from "firebase-admin";

// After initializing the Admin SDK with your service account:
const customToken = await admin.auth().createCustomToken(uid);
// Exchange the custom token for an ID token using the REST API

For server-to-server calls, use a service account with Firebase Admin SDK and create a custom token, then exchange it for an ID token via the Firebase Auth REST API.

Sending the Token

Include the token in the Authorization header of every request:

Authorization: Bearer <idToken>

Example:

GET /v2/analytics?type=employee&employeeId=abc123&environment=live
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Which Endpoints Require Auth

When a token is provided on optional endpoints, the createdBy field on the created record is set to the authenticated user's UID.

Roles and Permissions

Every authenticated user has a numeric role stored in their Firestore user document:

The role is validated server-side. Attempting to access a resource outside your role scope returns 403 Forbidden.

Scope Validation

In addition to role level, the API validates that the authenticated user has access to the specific organization, property, or department being queried. For example:

• A PropertyAdmin at Property A cannot read data for Property B.
• An Employee can only read their own tip and dividend records.

Pass the correct propertyId or organizationId in your requests and ensure your token belongs to a user with the appropriate role at that scope.

Token Errors