API authentication

Getting a key

1. Go to karani.co/account/services.

2. Find the API card and click Get Key.

3. Copy the key.

Shown once

The key is displayed a single time. Store it somewhere safe immediately. Refresh generates a new key and invalidates the old one — which breaks anything already using it.

Using it

Pass the key as an api_key parameter on every request:

curl "https://karani.co/api/v1/contacts?api_key=YOUR_KEY"

Errors

All errors use the same shape as successful responses, with success: false.

{
  "success": false,
  "message": "Forbidden",
  "type": "",
  "data": []
}

Status	Meaning
401	Unauthorized
403	Forbidden — usually a missing or invalid key
404	Not Found — the record doesn’t exist, or isn’t in your account

Scope and security

A key acts as the user it belongs to, on their account. There’s no read-only mode and no per-endpoint permissions.

Server-side only

A Karani API key grants full access to your donor data — names, addresses, giving history. Never put one in client-side JavaScript, a mobile app, or a public repository. Anything that ships to a user’s device will leak it.

Practical handling:

• Store the key in an environment variable, not in code.
• Keep it out of version control, logs, and error reports.
• Refresh it if you think it’s been exposed — and remember that breaks anything using the old one.

Rate limits

Be reasonable. If you’re pulling your whole contact list, do it on a schedule rather than in a loop, and cache the result.

Which account a key acts on

The key’s owning user, on their account. If you have several accounts or work in a shared account, check you generated the key while in the account you mean to act on.