Authentication and BYOK

You can process and retrieve reports without an account. A BiomAPI key provides assigned per-user quotas. A Gemini key selects your own Google account for PDF/image extraction.

Access	What it changes
No key	Public per-IP allowances
BiomAPI key	Quotas assigned to your API user
Gemini key (BYOK)	Extraction uses your Google key and BiomAPI’s separate BYOK allowance
Both keys	Your Gemini key, with the BYOK quota assigned to your BiomAPI user

Anyone with the full BiomPIN can retrieve a share. A BiomAPI key does not restrict retrieval to its owner. See BiomPIN for sharing boundaries.

Use a BiomAPI key

Pass the key in the Authorization header. This example reads it from a local environment variable:

curl --fail-with-body https://biomapi.com/api/v1/biom/usage \
  -H "Authorization: Bearer $BIOMAPI_KEY"

The API also accepts ?api_key=.... Use the header to keep keys out of URLs. In the usage response, keys.biomapi reports whether the key is valid. For a valid key, it also reports the user ID.

To discuss an API key or higher quotas, use Contact in the web app.

Use your own Gemini key

BYOK means bring your own key. Set GEMINI_API_KEY in your local environment, then send it as X-Gemini-API-Key:

curl --fail-with-body https://biomapi.com/api/v1/biom/process \
  -H "X-Gemini-API-Key: $GEMINI_API_KEY" \
  -F "file=@report.pdf" \
  -o result.json

BYOK applies only to PDF/image extraction. JSON uploads do not call Gemini. BYOK always uses AI Studio and replaces the managed credential for that request. If your key fails, BiomAPI does not retry with managed credentials.

Your Google account’s quota and processing terms apply alongside BiomAPI’s credit limits. Review Gemini processing and privacy before uploading patient data.

Validate a Gemini key

curl --fail-with-body 'https://biomapi.com/api/v1/biom/usage?validate=true' \
  -H "X-Gemini-API-Key: $GEMINI_API_KEY"

This checks the key against the live Gemini API. Without validate=true, the usage response reports only whether you supplied a Gemini key. It does not check validity.

Save keys in the web app or CLI

The web app’s status bar accepts both keys and stores them in that browser. The CLI supports interactive setup, environment variables, and command flags. Prefer interactive setup or environment variables to avoid typing secrets into shell history.