Authentication

GemInHay APIs are authenticated with a per-organization API key. Keys come in two environments — Test and Live — that meter, bill, and rate-limit independently of each other.

Header format

Every request must include:

Authorization: Bearer sk_<env>_<secret>

For example:

curl https://api.geminhay.com/v1/profile/infer-preferences \
  -H 'Authorization: Bearer sk_test_••••••••' \
  -H 'Content-Type: application/json' \
  -d '{ … }'

Test vs. Live

Environment	Prefix	Purpose
Test	sk_test_	Development. Counts against your dev quota; no real billing.
Live	sk_live_	Production traffic. Counts against your subscription tier.

The two environments are completely isolated: usage in one never affects the other's quota or billing. Test keys returns synthetic / safe data when the underlying call cannot be safely run in dev mode.

Key rotation

When you rotate a key in API Keys → Rotate, the old secret remains valid for 24 hours so you can roll deployments without downtime. After 24 hours, the old secret returns 401 Unauthorized permanently.

Partner events

Several analytics features (opener reply rate, end-user retention) require your application to report outcome events back to GemInHay. Send them to:

POST https://api.geminhay.com/v1/events
Content-Type: application/json
Authorization: Bearer sk_<env>_<secret>

[
  {
    "ts": "2026-04-24T10:15:32Z",
    "end_user_id": "<sha256-of-your-user-id>",
    "event": "conversation_reply",
    "idempotency_key": "<uuid>",
    "context": { "originating_request_id": "req_…" }
  }
]

end_user_id must be hashed on your side — we never accept raw user identifiers, emails, or PII. See the design notes on partner events for the full schema and idempotency rules.