Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt

Use this file to discover all available pages before exploring further.

API keys authorize calls into the Synheart Platform from the Synheart SDKs and your backend code. Keys are issued per-app, owned by an organization, and managed from the developer portal at platform.synheart.ai.
The CLI uses OAuth Device Flow, not API keys, for synheart login. Generate an API key only when you need server-to-server or SDK-to-platform access. See Authenticate the CLI.

​
What a key carries

Each key the portal issues is bound to:
  • An organization (selected from the org switcher).
  • An app inside a project — keys are minted at the app level, so one key can’t speak for multiple apps.
  • A label you supply (free-form, used to identify the key in the list).
  • One or more scopes that grant CRUD permissions: read, write, delete, admin.
  • An environment tag for your own bookkeeping: production, development, staging, testing, or other.

​
Generate a key

  1. Open the developer portal and switch to the organization, tenant, and project that own the app.
  2. Open the app’s API keys tab and choose Create key.
  3. Set the label, environment, and the scopes you want.
  4. The portal returns a secret key and a signing secret in a one-time dialog. Both are shown only once and stored hashed — copy them immediately into a secret manager.
You can also download a credentials JSON containing the org id, tenant id, project id, app id, secret key, and signing secret. Treat the file like any other credential — it shouldn’t land in source control.

​
Ingestion access

Reading data and pushing biosignals share the same key surface, but biosignal ingestion is gated by an app-level allowlist maintained by Synheart. Keys for apps that aren’t on the list are rejected at ingestion time with the message “App <app_id> is not verified for data ingestion.” If you need ingestion access, contact Synheart with the platform app_id shown on the App in the dashboard — there’s no self-service request flow today.

​
Rotate

There’s no automatic rotation. To rotate:
  1. Generate a new key with the same scopes and environment.
  2. Roll both the secret key and signing secret out to your callers.
  3. Revoke the old key.

​
Revoke

Revoke unused keys from the API keys list. Revocation is immediate — subsequent requests with the revoked key fail with 401. Revoked keys stay visible in the list (toggle Include revoked) for audit.

​
Errors

StatusMeaning
401Missing, malformed, or revoked key. Re-check that the x-api-key header is set and the key isn’t revoked.
403Key is valid but not authorized — either the app isn’t allowlisted for ingestion, or the request body’s app_id doesn’t match the key’s app.
429Rate limit exceeded. Back off and retry.

​
Next

Projects & wearables

Organize the apps your keys point at into projects, and connect the devices that produce session data.