Authentication
Create an API key, send it with every request, and keep it safe.
Every Org API request carries your organization's API key in the X-Api-Key header. The key is the only thing that says which organization you're working with. There's no organization id or slug in the URL.
Create a key
You need to be an admin of the organization to manage API keys.
Open the API keys page
In the dashboard, go to Settings → API keys. The direct address is lahuta.org/dash/<your-org>/api-keys, for example lahuta.org/dash/northside-pottery/api-keys.
Create the key
Select Create API key. Give it a Name that says where it's used, like "Website" or "Front desk tablet", then select Create API key again to confirm.
Copy it right away
The Save your key dialog shows the key once. Select Copy and close and paste it straight into your server's environment variables or secret manager. If you lose it, create a new key.
About the Permissions list
The Create API key dialog may show a Permissions list. The Org API doesn't check permissions yet, so every key has full access to every Org API endpoint for its organization, whatever you select there.
Send the key
Put the key in the X-Api-Key header of every request.
curl https://api.lahuta.org/v1/events \
-H "X-Api-Key: $LAHUTA_API_KEY"What a key can do
- One key, one organization. A key belongs to the organization it was created in. If you run two organizations, create a key in each.
- Full access. There are no scopes yet. A key can read and write everything the Org API offers for its organization: contacts, groups, emails, checkouts, bookings and the rest.
- Shared limits. All keys of one organization share the same rate limits.
Keep it secret
Anyone who has your key can add contacts, email your customers from your organization and open payment pages in your name. Treat it like a password.
- Keep it on your server, in an environment variable or secret manager. Never put it in browser JavaScript, a mobile app or a public repository.
- Have your site's front end call your own server, and let your server call Lahuta. Browsers can't call the Org API from other websites: the API doesn't allow the
X-Api-Keyheader in cross-site requests, so those calls fail before they reach Lahuta. - Use one key per site or tool. Then you can revoke one without breaking the others, and the Last used column tells you which ones are active.
Rotate or revoke a key
To rotate a key, create a new one, deploy it to your server, check that requests work, then revoke the old one.
To revoke a key, open the actions menu on its row, select Revoke key, and confirm with Revoke key in the Revoke API key? dialog. This can't be undone. Requests that use the key are refused from then on.
If a key leaks, revoke it first, then create a replacement.
When a key is refused
A missing, wrong or revoked key gets a 401 with this body:
{ "_tag": "Unauthorized" }The same response comes back if the key's organization no longer exists. Rarely, a 401 means Lahuta couldn't check the key at that moment. If a key that worked a minute ago gets a 401, retry once before you rotate it.
The one exception: signed-in visitors
GET /v1/me is the only endpoint that also takes a second credential. Next to your API key, you send the access token of the person signed in to your site, as Authorization: Bearer <token>. You'd use it when your site signs people in with their Lahuta account and you want to know who they are, or whether they're on your team. See Signed-in visitors.