API Keys
API keys let your own systems, like Zapier, your CRM or a BI warehouse, call the Taalk API. Each key only reaches the scopes and data you allow. Treat keys like passwords, and create one key per system so you can limit, rotate and revoke each one on its own.
Go to Developer › Integrations. Under API access, open Taalk API Token. The add-on is free, but API keys need a paid plan: on a free workspace the page shows Subscribe to unlock API keys with a Go live button.
What you see
- Summary: active keys, keys expiring in the next 30 days, keys unused for 30+ days (candidates to revoke), and API requests across all your keys in the last 48 hours.
- Your keys: name and created date, the last 4 characters of the key, access, last used, and expiry. Each key has a status: Active, Expiring (within 30 days), Expired or Unused (never used).
- Connected-service keys: keys Taalk created for services it connects to, such as Twilio inbound calls, media attachments or the embedded iFrame. The Used by column shows what relies on each one. Revoking one stops that service until it is set up again.
Create a key
- Click Create key.
- Enter a Name you'll recognize in logs and usage, for example "Zapier production". Add an optional Description (up to 100 characters).
- Under Access, keep Full access or choose Restricted and set each scope you need to Allowed (see below).
- Optional: pick a Data source (if you work in more than one workspace) and a Rate limit.
- Under Expires, choose 30 days, 90 days, 1 year (default) or Custom (any date up to 10 years out).
- Click Create key.
- Copy the key, store it in your secrets manager, tick I've stored this key and click Done.
The full key is shown only once. After that, Taalk shows only its last 4 characters. If you lose a key, rotate it.
You can have up to 15 keys. At the limit, Create key is disabled until you revoke one.
Restricted access
A Restricted key can only call the scopes you allow. Every other request returns 401. You must allow at least one scope.
| Scope | The key can only... |
|---|---|
| Contact form | Send leads to POST /contact_form/{campaignId}. Use this for a key you embed in a public web form |
| Read attachments | Download attachments |
| Chatbot | Use the chatbot endpoints |
| iFrame embedding | Open the embedded console. See Embed Taalk in an iFrame |
Rate limit
| Option | What it allows |
|---|---|
| Unlimited (default) | No per-key limit |
| 10 per hour | Low-volume use, such as a public form |
| 3,600 per hour | Steady integrations |
Requests over the limit return 429. The response has a RateLimit header that tells you when to retry.
Use a key
Send the key in the Authorization header:
curl https://api.taalk.ai/api/campaign2s \
-H "Authorization: Bearer $TAALK_API_KEY"
If you belong to several workspaces, add ?db=<workspace ID>. See API and Developer Access.
Anyone with your key can act as you in Taalk, including placing calls. Keep keys on your server, never in browser code, except a Contact form key.
Rotate, edit or revoke
Use the ⋯ menu on a key's row:
| Action | What it does |
|---|---|
| Edit name and description | Renames the key. Access, rate limit and expiry stay the same |
| Rotate | Issues a new key with the same access and lifetime, shown once. The old key stops working right away, so update your systems with the new one. Not available for connected-service keys |
| Revoke | Type the key's name to confirm. Anything using the key stops working right away. This can't be undone |
Test a request
- Click API docs at the top of the page.
- Open an endpoint, for example List campaigns.
- Click Test request and send it.
The docs use a short-lived token for your current workspace, so you don't need to paste a key. To check a key you made, run the same request with curl and your key. A 200 response means the key works, and Last used updates on its row.
Tips
- Use one key per system so you can rotate or revoke it without affecting others.
- Revoke keys that have gone unused for 30+ days.
- Rotate a key straight away if you think it has leaked.
- Watch Expiring in 30 days and rotate those keys before they expire.
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| 401 on every request | Wrong, expired or revoked key, or missing Bearer |
Check the key's status, then send Authorization: Bearer <key> |
| 401 on some endpoints only | The key is Restricted | Create a key with Full access, or one that allows that scope |
| 401 "no data access" | db is a workspace you can't access |
Check the workspace ID |
| 402 on key requests | Free workspace | Go live on a paid plan |
| 429 | Rate limit reached | Slow down or use a key with a higher limit |
| Lost the full key | Keys are shown once | Rotate the key and store the new one |
What API keys can't do (yet)
- Change a key's access, rate limit or expiry after creating it. Create a new key instead.
- Make a read-only key for the full API. Restricted scopes only cover the four actions above.