Authentication

Overview

GrantMaster secures almost all REST API endpoints under /api/v1/* with a unified authentication middleware that supports three methods:

• Firebase Auth ID tokens in the Authorization header
• API keys in the X-API-Key header
• Portal tokens for read-only portal access

Permissions are enforced with Firestore role-based access control (RBAC) for the resolved organization context. Each authenticated request runs with the roles and permissions associated with that organization.

Supported authentication methods

1. Firebase Auth ID token (Authorization bearer)

Use a Firebase Auth ID token when you call the API on behalf of an authenticated user in your application.

Send the ID token from Firebase Auth in the Authorization header using the Bearer scheme.

curl "<YOUR_BASE_URL>/api/v1/projects" \
  -H "Authorization: Bearer <FIREBASE_ID_TOKEN>"

When you authenticate with an ID token:

• The middleware verifies the token signature and expiry with Firebase Admin.
• The user and organization context are derived from the decoded token and Firestore.
• RBAC permissions for that organization's roles determine which endpoints and resources the user can access.

2. API key (X-API-Key)

Use an API key for server-to-server integrations where you do not have an end-user context. API keys are stored in the apiKeys collection and validated by hashing (SHA-256) the incoming key and looking up the stored record.

Send the key in the X-API-Key header.

curl "<YOUR_BASE_URL>/api/v1/projects" \
  -H "X-API-Key: <API_KEY>"

Key characteristics of API key auth:

• Keys may be scoped to specific organizations and permissions.
• Keys can be restricted to certain operations or resources via scopes/permissions in Firestore.
• Keys are suitable for backend jobs, cron tasks, and integrations that do not rely on a user session.

3. Portal token (limited read-only access)

Portal tokens provide restricted, typically read-only access for portal-style use cases, such as embedding reports or exposing a limited subset of data.

The middleware recognizes portal tokens:

• As a bearer token in the Authorization header (for example, Bearer portal_...), or
• As a query parameter token (for example, ?token=portal_...), depending on how you configure access.

Portal tokens are stored in the portalTokens collection and map to a constrained set of permissions such as VIEW_PROJECTS or VIEW_REPORTS.

curl "<YOUR_BASE_URL>/api/v1/reports/summary" \
  -H "Authorization: Bearer <PORTAL_TOKEN>"

Portal tokens always run under a narrowed permission set and organization scope, making them appropriate for sharing limited access with external stakeholders without granting full API capabilities.

Permissions and organization scoping

After authentication, the middleware determines which organization the request belongs to and loads roles and permissions for that organization from Firestore. All subsequent authorization decisions happen within this scoped context.

Key points:

• Each resolved principal (user, API key, or portal token) is associated with one or more organizations.
• Roles and permissions for that organization are fetched from Firestore.
• Every secured route under /api/v1/* checks these permissions before performing the requested operation.

If a caller is authenticated but lacks the required permission, the API returns an authorization error even though the token or key itself is valid.

Unauthenticated health endpoint

The REST API exposes an unauthenticated health check for monitoring and uptime probes:

curl "<YOUR_BASE_URL>/api/v1/health"

Use this endpoint for liveness and readiness checks in infrastructure tooling. All other /api/v1/* endpoints go through the authentication middleware and require one of the supported auth methods.

Troubleshooting authentication