Authentication

Every request to the Hone ingestion API carries one header:

x-api-key: sk_1a2b3c...

That is the whole model. A valid key authorizes writes for the organization that owns it. There is no separate account id to route on and no token exchange to perform.

Where keys come from

API keys are issued in the Hone dashboard under Settings → API Keys. Give each key a name that describes where it runs, for example production or staging, so you can revoke the right one later without guessing. A key is a string that starts with sk_ followed by a hexadecimal secret:

sk_9f3c0d7e5b2a41c88e6f0a1b2c3d4e5f...

Keys are scoped to your organization and do not expire on a timer. They stay valid until you delete them from the dashboard.

Sending the key

The SDKs take the key at initialization and attach the header for you.

import honeai

honeai.init("sk_your_key_here")

import { init } from "@hone/sdk";

init("sk_your_key_here");

curl https://api.hone.dev/api/v1/capture-event \
  -H "x-api-key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "event_id": "...", "session_id": "...", "primitive_name": "support-bot", "args": "hi", "result": "hello" }'

Endpoints

Production

https://api.hone.dev

Local development

http://localhost:8080

Point the SDK at a different base URL with the endpoint option when you need to (for example, a local stack):

honeai.init("sk_your_key_here", endpoint="http://localhost:8080")

init("sk_your_key_here", { endpoint: "http://localhost:8080" });

Keep keys out of source control

An sk_ key is a write credential. Anyone holding it can push events into your organization.

Never commit an API key to a repository, paste it into a ticket, or ship it in client-side code that reaches an end user’s browser or device.

Sound practice:

Load the key from an environment variable or a secrets manager, never a literal in code.
Use separate keys per environment so you can revoke one without disturbing the others.
Rotate a key by creating a new one, deploying it, then deleting the old one from Settings → API Keys.
If a key is ever exposed, delete it immediately. Deletion takes effect for all future requests.

import os
import honeai

honeai.init(os.environ["HONE_API_KEY"])

import { init } from "@hone/sdk";

init(process.env.HONE_API_KEY!);

​Where keys come from

​Sending the key

​Endpoints

Production

Local development

​Keep keys out of source control

Where keys come from

Sending the key

Endpoints

Keep keys out of source control