Authentication

All tenant-scoped endpoints require an Authorization: Bearer <token> header. Tokens are issued by Google Identity Platform (Firebase Auth) after sign-in.

Token format

Tokens are standard OIDC JWTs. The issuer is https://securetoken.google.com/{projectId}. The platform validates the token on every request — no session or API key is stored server-side. The principal_id derived from your token takes the form:

oidc:{projectId}#{firebaseUid}

This is the identifier used in member records, audit logs, and ownership attribution.

Getting a token

If you’re calling the API from a browser-based app:

import { getAuth } from "firebase/auth";

const auth = getAuth();
const token = await auth.currentUser.getIdToken();
// token is valid for 1 hour; refresh as needed

For server-to-server or testing use the Firebase Admin SDK or the REST sign-in endpoint with a service account.

Using the token

Pass the token as a Bearer header on every request:

curl -H "Authorization: Bearer $TOKEN" \
  https://tally-platform-api-iikaevm4pq-ue.a.run.app/v1/meta

Access control

Authentication establishes your identity. Authorization is a separate layer:

Tenant membership — your principal must be a member of the tenant you’re acting on behalf of, with an appropriate role.
Ownership — writes and administrative actions require the tenant to own the subject.
Grants — counterparty read access is controlled by explicit grants issued by the owning tenant, plus a per-principal allow_counterparty_access flag.

See Access Grants and Principals & Roles for details.

Principal types

Every principal has a principal_type that distinguishes how it authenticates and operates:

Type	Description
`human`	An interactive user authenticated via OIDC/Firebase. Default for all new principals.
`service_account`	A non-interactive integration credential (API key, CI runner, etc.). Deterministic, same code path every call.
`ai_agent`	A reasoning-based caller that invokes an LLM as part of its operation. Non-deterministic; requires explicit classification.

curl -X PUT https://tally-platform-api-iikaevm4pq-ue.a.run.app/v1/tenants/{tenant_id}/principals/{principal_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_functional_role": "tenant_reader",
    "principal_type": "service_account"
  }'

Human-only constraints

Certain privileged actions require the calling principal to have principal_type: human. Service account and AI agent callers are rejected with 422:

Setting allow_counterparty_access: true — enabling counterparty data visibility for a principal must be an explicit human decision. The account_admin making this call must be using their own OIDC session token, not an API key.
Assigning api_functional_role: tenant_owner — the ownership accountability role may not be held by an automated caller.

Revoking these (setting allow_counterparty_access: false or downgrading from tenant_owner) carries no human-caller requirement.

Unauthenticated endpoints

The following endpoints do not require a token:

GET /health
GET /v1/meta
GET /v1/ops/readiness

Overview

Concepts

Token format

Getting a token

Using the token

Access control

Principal types

Human-only constraints

Unauthenticated endpoints

​Token format

​Getting a token

​Using the token

​Access control

​Principal types

​Human-only constraints

​Unauthenticated endpoints

Token format

Getting a token

Using the token

Access control

Principal types

Human-only constraints

Unauthenticated endpoints