API keys

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.

​

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 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 of Read, Write, Delete, Admin. 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 (CI lookups, support tickets) and the one above for SDK / backend wiring. Use the secret key as app_api_key when configuring the runtime — see Runtime configuration. The two secrets serve different callers:

• secret_key authenticates every request via the x-api-key header. The on-device SDK uses this.
• signing_secret is an HMAC-SHA256 key for server-to-server callers that sign ingest requests directly (RFC dual-mode auth Mode B). The on-device SDK does not use this — it signs with an ECDSA P-256 device key registered through synheart-auth. Only set up signing_secret if your backend bypasses the SDK and calls the platform REST API directly (e.g. from a Postman collection or server-side ingest pipeline).

​

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

​

Next