Authentication

The Happily.ai API uses API key authentication. Every request must include your secret key in the x-api-key header. There are no OAuth flows or access tokens to manage.

Getting a key

Sign in to your Happily account and visit my.happily.ai/integrations to generate a key. Developer access is enabled by your Customer Success contact, so reach out if you don't see the integrations page.

Keys are issued per company and per stage. A single key authenticates as your whole company; all data you read and write is scoped to it.

Using your key

Send the key in the x-api-key header on every request:

curl "https://api.happily.ai/prod/1/questions" \
  -H "x-api-key: $HAPPILY_API_KEY"

fetch("https://api.happily.ai/prod/1/questions", {
  headers: { "x-api-key": process.env.HAPPILY_API_KEY },
});

requests.get(
    "https://api.happily.ai/prod/1/questions",
    headers={"x-api-key": os.environ["HAPPILY_API_KEY"]},
)

Stages

Your key is bound to one stage, and the stage is part of the base URL:

Stage	Base URL	Use for
`prod`	`https://api.happily.ai/prod/1`	Live company data.
`dev`	`https://api.happily.ai/dev/1`	Testing and development.

Using a prod key against the dev base URL (or vice versa) returns 403 Invalid API Key by stage. Match the key to the stage in the URL.

Errors

Response	Meaning
`403 Forbidden`	The `x-api-key` header is missing.
`403 Invalid API Key.`	The key was not recognized.
`403 Invalid API Key by stage.`	The key is valid but not for the stage in the URL.

Keeping your key safe

Caution

Anyone with your key can read and modify your company's data. Treat it like a production database password.

Store keys in environment variables or a secrets manager, never in source control.
Never call the API directly from browsers or mobile apps. Proxy through your backend.
Rotate keys from the integrations page if one is exposed. Generating a new key lets you retire the old one.
Use a dev key for testing so production data stays clean.