Authentication

API keys

An administrator creates keys under Settings → API keys in the OpenHouse app. The full secret — it starts with oh_ — is shown exactly once, at creation: store it in your secret manager, because it cannot be retrieved again. Send it on every request:

curl -s https://openhouse-api.6drei2.com/ingest/contacts \
  -H "Authorization: Bearer oh_..." -H 'Content-Type: application/json' \
  -d '{"records": [...]}'

• Keys don't expire — they work until an administrator revokes them, and revocation takes effect on the very next request.
• A key is scoped to one organization and acts with the role it was given at creation — operator by default, which covers everything in this documentation. An administrator can change a key's role later under Settings → API keys; the change applies from the key's next request.
• Every action a key performs appears in the organization's audit log under the key's own name — give each integration its own key, so the trail stays readable and one credential can be rotated without touching the others.
• A missing, malformed or revoked key is a 401; an action above the key's role is a 403.

Alternative: signing in as a user

For one-off scripts you can authenticate as a real user instead. Note the token is short-lived — 15 minutes — which is fine for a script that signs in and runs, and wrong for anything long-running: use an API key for those.

curl -s https://openhouse-api.6drei2.com/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@your-org.com", "password": "..."}'

# 200 →
{ "token": "eyJhbGciOi...", "user": { "email": "...", "role": "operator", ... } }

Send the token as Authorization: Bearer <token>. Sign-in is rate-limited (5 attempts per minute), and invalid credentials are a 401.