Kom i gang

API-nøkler og tilganger

Hvert kall bærer en API-nøkkel. Nøkkelen sier hvilken bedrift kallet gjelder, om det gjelder hele bedriften eller én profil, hva det har lov til, og om det er en test.

Send nøkkelen

Legg nøkkelen i headeren Authorization: Bearer <nøkkel>. En nøkkel starter med tk_live_ eller tk_test_, og etter et punktum følger hemmeligheten. Uten gyldig nøkkel svarer API-et 401 med koden unauthenticated.

Les saldoen

curl "https://api.telkit.no/v1/balance" \  -H "Authorization: Bearer $TELKIT_API_KEY"

const response = await fetch("https://api.telkit.no/v1/balance", {  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,  },});const answer = await response.json();

Du lager nøkler i dashbordet under Utviklere (rollen Utvikler eller høyere). Hemmeligheten vises bare én gang, når nøkkelen lages. Vi lagrer den ikke, så en nøkkel du har mistet, må du trekke tilbake og lage på nytt.

Hele bedriften eller én profil

En profil er en avdeling, en butikk eller et produkt i bedriften, med egne avsendere, numre og eventuelt en egen månedsgrense. En nøkkel kan gjelde én profil eller hele bedriften:

En profilnøkkel sender, ringer og leser bare for sin profil. Den ser ikke hendelser som gjelder hele bedriften, som balance.low.
En bedriftsnøkkel gjelder alle profilene. Der et kall trenger en profil, sier du hvilken med profile (kortnavnet) eller profileId.

Tilganger

En nøkkel kan begrenses til noen tilganger. Uten liste (scopes: null) har den alle. Et kall som krever en tilgang nøkkelen mangler, får 403 med koden scope_missing.

Tilgang	Betyr
`sms:send`	Sende SMS
`sms:read`	Lese SMS
`email:send`	Sende e-post
`email:read`	Lese e-post
`letters:send`	Sende brev
`letters:read`	Lese brev
`calls:write`	Ringe og styre samtaler
`calls:read`	Lese samtaler
`numbers:manage`	Bestille og endre numre
`numbers:read`	Lese numre
`agents:manage`	Styre AI-agenter
`solutions:manage`	Styre løsninger
`transcription:write`	Transkribere lyd
`transcription:read`	Lese transkripsjoner
`webhooks:manage`	Styre webhooks
`events:read`	Lese hendelser
`profiles:manage`	Opprette og endre profiler. Bare for nøkler som gjelder hele bedriften.
`keys:manage`	Lage og trekke tilbake nøkler. Bare for nøkler som gjelder hele bedriften.
`contacts:manage`	Styre kontakter
`usage:read`	Lese forbruk og saldo

En nøkkel kan selv lage nøkler med POST /v1/api-keys når den har keys:manage. Den nye nøkkelen gjelder alltid én profil, får aldri flere tilganger enn nøkkelen som lager den, og en testnøkkel kan ikke lage en ekte nøkkel.

Lag en nøkkel som bare kan sende SMS for én profil

curl -X POST "https://api.telkit.no/v1/api-keys" \  -H "Authorization: Bearer $TELKIT_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "name": "Nettbutikkens ordresystem",  "mode": "live",  "profileId": "0199e4a2-7c1b-7d3e-9a41-5f2c8b6d1e07",  "scopes": [    "sms:send",    "sms:read"  ]}'

const response = await fetch("https://api.telkit.no/v1/api-keys", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({    name: "Nettbutikkens ordresystem",    mode: "live",    profileId: "0199e4a2-7c1b-7d3e-9a41-5f2c8b6d1e07",    scopes: [      "sms:send",      "sms:read",    ],  }),});const answer = await response.json();

Testnøkler og ekte nøkler

En testnøkkel (tk_test_) sender ingen SMS, e-post eller brev, ringer ingen og trekker ingenting fra saldoen. Svaret har testMode: true, eller mode: "test" der feltet heter det.

Hendelser fra en testnøkkel har mode: "test". En nøkkel leser bare hendelser i sin egen modus.
Et webhook-endepunkt har også en modus. Lag et eget endepunkt med mode: "test" for testhendelsene.
En testnøkkel kan ikke opprette eller endre profiler.

Trekk tilbake en nøkkel