API keys

API keys authorize calls into the Synheart Platform from your backend code and from desktop hosts. Keys are issued per-app, owned by an organization, and managed from the developer portal at platform.synheart.ai.

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 name the services the key may call (see Scopes).
• An environment tag for your own bookkeeping: production, development, staging, testing, or other.

Scopes

Scopes use a resource:action format. A key can call only the services its scopes name; anything else is rejected.

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 Generate API Key.
3. In the side panel, set:
   • Choose App: the key is bound to one app.
   • Key Type: Production, Development, Staging, Testing, or Other.
   • Scopes: tick at least one scope from the table below. The form blocks submission until one is selected.
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. The dialog also offers a Download credentials JSON button that bundles the new secrets together with the identifiers: org_id, tenant_id, project_id, app_id, secret_key, and (when present) signing_secret. Save it to your secret manager; it never appears again.

The app detail page exposes a separate credentials JSON download that contains only the four identifiers (no secrets). Use that one for non-sensitive contexts such as CI lookups, support tickets, and the app_id / org_id your mobile app needs. The two secrets are used together by callers that can keep them secret: your backend, a server-side ingest pipeline, or a desktop host.

• secret_key is sent on every request in the x-api-key header.
• signing_secret signs ingest, consent, and sync requests with HMAC-SHA256, sent as X-Synheart-Signature. A desktop host passes both to the runtime’s HMAC configuration so it can upload without device registration. See Runtime configuration.

Ingestion access

Ingestion is gated per organization, not per app. There is no app allowlist: any app in your org can upload once its requests are authenticated (device attestation on mobile, or the signing secret on backend and desktop hosts). To enable lab ingestion, contact Synheart with your org_id; 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

Next