Getting started

1. Have API access enabled

External API access is granted per organization. If Settings → API Keys is not visible in your HeyKoala account, ask your account contact to turn it on — until then, every request answers 401.

2. Mint a key

Settings → API Keys → Create key. You choose:

• A name. Whatever helps you recognise it later — usually the system that will use it (Zapier, CRM sync, staging).
• Scopes. Per resource, read or write. Grant the least you need; see Scopes and permissions.
• Destructive actions. Off by default. Only turn it on if the integration genuinely needs to stop campaigns or delete documents.
• An expiry, optionally.

The plaintext key is shown once, at creation. We store only a hash, so it cannot be recovered — if you lose it, revoke it and mint another.

Keys look like hk_api_ followed by a long random string.

3. Make a request

Send the key as a bearer token on every request:

curl https://dvoice.heykoala.ai/api/v1/ext/ \
  -H "Authorization: Bearer hk_api_..."

That endpoint reports exactly what the key can do:

{
  "status": true,
  "message": "External API capabilities retrieved.",
  "data": {
    "organization": "Acme Travel",
    "key": "CRM sync",
    "expires_at": null,
    "allow_destructive": false,
    "resources": [
      {
        "resource": "contacts",
        "path": "/api/v1/ext/contacts/",
        "granted": "write",
        "supports": ["read", "write"],
        "operations": ["create", "delete", "get", "list", "update"]
      }
    ]
  }
}

It is generated from the same registry that serves the requests, so it cannot disagree with reality. Prefer calling it over hardcoding assumptions about what a key can reach.

Base URLs

Build against development first. Calls placed there are real calls on real telephony and consume real credits — the difference is which organization's data you are touching, not whether the phone rings.

Keeping the key safe

The key carries your organization's data and can spend its credits. Treat it like a password:

• Server-side only. Never ship it in a browser bundle, mobile app, or anything a customer can view source on.
• One key per integration, so you can revoke one without breaking the others.
• Revoke immediately if it leaks — revocation takes effect on the next request, and there is no grace period to wait out.