Authentication & API Keys

Every pipeline call is authenticated with a bearer token. For server-to-server integration that token is a programmatic API key — an opaque string prefixed hfk_. A key is an application credential you issue and revoke yourself; it is unrelated to InvesTeam's keyless GCP infrastructure. This page covers how the edge authenticates a key, the scopes a key carries, and how keys are issued, rotated, and revoked.

How do I authenticate a request?¶

Send your key as a bearer token on every call:

bash

curl -sS https://investeam.io/api/v1/briefs \
  -H "Authorization: Bearer hfk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"input": "Is NVDA a buy right now?"}'

import requests

resp = requests.post(
    "https://investeam.io/api/v1/briefs",
    headers={"Authorization": "Bearer hfk_your_key_here"},
    json={"input": "Is NVDA a buy right now?"},
)
print(resp.status_code, resp.json())

The edge is dual-mode: it accepts either a programmatic hfk_ key or a Firebase Identity Platform ID token (the browser product's credential), and it never falls back from one to the other. A token beginning with hfk_ is treated as a programmatic key; any other bearer is verified as a Firebase ID token. A key that fails verification returns 401 unauthorized and is never retried as a Firebase token.

What is an InvesTeam API key (`hfk_…`)?¶

An hfk_ key is an application credential for your integration — not a GCP credential. InvesTeam's own cloud access stays keyless (Workload Identity Federation and Application Default Credentials); an hfk_ key never touches that layer. The key is terminated at the public edge: it is verified there and is never forwarded to any internal service. The edge rebuilds its own internal credentials before touching the pipeline, so your key resolves to a principal and its scopes and goes no further.

Treat an hfk_ key like a password. It grants pipeline access as your principal and spends your kickoff quota. Store it in a secret manager, never in source control or a client-side bundle, and revoke it immediately if it leaks.

How do I get an InvesTeam API key?¶

Keys are issued on the auth service, reachable only through an interactively signed-in (Firebase) user — never with an hfk_ key itself. When a key is issued you receive the plaintext exactly once; it is never stored in the clear and never shown again, so capture it into your secret store at that moment.

The exact key-issuance request shape lives on the auth service and is outside this HTTP reference. Confirm the issuance flow in your InvesTeam account before wiring a "get a key" step into automation.

What are InvesTeam API key scopes?¶

A programmatic key carries scopes, and each pipeline route requires one. A key missing a route's scope receives 403 forbidden. A signed-in Firebase user is implicitly full-scoped on their own sessions and is not scope-gated.

Scope	Grants
`pipeline:read`	The poll/read routes: `GET /api/v1/sessions`, `GET /api/v1/briefs/{id}`, `GET /api/v1/orchestrations/{id}`, `GET /api/v1/executions/{id}`, `GET /api/v1/executions/{id}/transcript`
`pipeline:write`	The submit routes: `POST /api/v1/briefs`, `POST /api/v1/briefs/{id}/answers`, `POST /api/v1/orchestrations`
`pipeline:findings`	`GET /api/v1/analyses/{id}` — the final synthesized analysis. This is the premium object: a read+write key without `pipeline:findings` can poll execution status but is `403`ed on the analysis.

A typical read-and-run integration needs pipeline:read + pipeline:write; add pipeline:findings to fetch the final analysis. Scope for least privilege — a key that only polls needs only pipeline:read.

How do I rotate an API key?¶

Rotate a key by issuing a successor and retiring the old one. Rotation is zero-downtime: the successor is minted, its plaintext is returned once, and the predecessor stays valid through a short grace window before it is revoked — so you can deploy the new key before the old one stops working. Because keys are application credentials, there is no long-lived secret to leak; rotate on a schedule and after any suspected exposure.

Like issuance, rotation is performed by the interactively signed-in owner on the auth service, never with an hfk_ key.

How do I revoke an API key?¶

Revoke a key to disable it immediately — its status flips to revoked and it stops authenticating on the next verification. Revoke the moment a key is no longer needed or may have leaked. Revocation, too, is an owner action on the auth service and can never be performed by a programmatic key.

Key management (issue, scope, rotate, revoke) is never available to an hfk_ principal — a leaked key can spend quota, but it cannot mint successors or survive its own revocation.

Where next?¶

With a scoped key in hand, learn the request pattern in the async submit → poll model, or run the whole pipeline in the Pipeline Walkthrough. For auth failures, see 401 and 403 in the Error Reference.