Keys and authentication
Every request carries a key. A key is two parts:
| Part | Looks like | Is it secret? |
|---|---|---|
| Key ID | ck_live_8Fq2LmZ0pR4tV6xY9aBcDe |
No. Safe to show and to log. |
| Secret | cs_live_... (43 more characters) |
Yes. Shown once, when you make the key. |
Test keys start ck_test_ and cs_test_.
Sending the key
Section titled “Sending the key”Use either of these. Both work on every endpoint.
HTTP Basic: the key ID as the username and the secret as the password. Most tools do this for you:
curl -u "$CALLVIEW_KEY_ID:$CALLVIEW_SECRET" 'https://v2-api.callview.ai/api/v1/external/campaigns'Bearer: the secret alone:
curl -H "Authorization: Bearer $CALLVIEW_SECRET" 'https://v2-api.callview.ai/api/v1/external/campaigns'Always use https://. Never send a key over plain http://: the request is not processed, but the key has already crossed the network unencrypted, so roll it. Today a plain http:// request gets a 301 redirect to https:// (don’t follow it: many HTTP clients turn a redirected POST into a GET); behind CallView’s edge it gets a 403 and never reaches the API.
A missing, wrong, revoked or expired key gets 401 with the code authentication_failed. The reason field says which one. After 20 failed tries from one address in 5 minutes, that address is blocked for 15 minutes (429).
Keys work only on the API described here (/api/v1/external). They can’t sign in to the CallView app or reach anything else.
Test keys and live keys
Section titled “Test keys and live keys”A live key works with your real leads and calls, and the leads you add get called. A test key doesn’t dial anyone and costs nothing. It can’t see or change real leads or calls: it gets sample data in the same shapes, so you can build your whole integration with it. See Test mode.
Both see your real campaign IDs and names, so moving from test to live means changing the key and nothing else.
What a key may touch
Section titled “What a key may touch”When you make a key in Settings > API, you choose:
- Which campaigns. A key limited to some campaigns can’t see or add leads anywhere else. Asking about another campaign gets
403 permission_denied. - What it can do. Read or Write, area by area: Leads, Calls, Campaigns, Callbacks, DNC, Webhooks, Events and Usage. A request outside that gets
403 permission_denied, naming what’s missing. Three ready-made sets help: CRM speed to lead, Reporting only and Full access. - A lead source (optional): stamped on every lead the key adds, so you can tell where leads came from.
- Allowed IP addresses (optional): requests from anywhere else are refused.
- When it stops working (optional).
- Limits: see Rate limits.
Give each system its own key, with only what it needs. A CRM that sends leads and reads outcomes needs Leads (read and write), Calls (read) and Events (read).
Keeping keys safe
Section titled “Keeping keys safe”Keep the secret on your server. Don’t put it in a web page, a mobile app or a public repository.
- Roll a key in Settings > API to get a new secret without making a new key. The old secret keeps working for a grace period you choose (24 hours unless you pick another, at most 7 days), so you can switch over without dropping a request.
- Revoke a key you no longer use. It stops working on the next request.
- If a secret leaks, revoke the key right away, or roll it with a grace period of 0 so the leaked secret dies at once.