API-nycklar och behörigheter

Ringhums REST-API låter dina egna system arbeta med din arbetsyta: lista samtal och transkriberingar, skapa assistenter, boka tider, hantera kontakter, ringa utgående samtal med mera. Varje förfrågan autentiseras med en API-nyckel som tillhör en arbetsyta. Den här artikeln beskriver hur du skapar nycklar och de konventioner som gäller för alla endpoints. Den fullständiga endpoint-referensen finns på /docs.

Vem kan hantera nycklar

API:et är tillgängligt på alla planer. Vad en nyckel kan göra begränsas ändå av din plan: att till exempel skapa en assistent utöver din plans gräns ger ett felmeddelande.

Skapa en API-nyckel

1. Öppna Utvecklare i sidomenyn.
2. I kortet API-nycklar klickar du på Skapa nyckel.
3. Ange ett Nyckelnamn som visar var nyckeln används, till exempel "Produktionsserver".
4. Under Behörigheter kryssar du i read, write eller båda.
5. Klicka på Skapa nyckel.
6. Kopiera nyckeln från den gröna rutan och spara den på ett säkert ställe, till exempel i din servers hemlighetslager. Klicka på Klart.

Viktigt: Nyckeln visas bara en gång. Ringhum sparar bara ett fingeravtryck av den, så den kan inte visas igen. Om du tappar bort den skapar du en ny nyckel och återkallar den gamla.

Nycklar börjar med ck_live_. Tabellen API-nycklar visar varje nyckels namn, de första tecknen i nyckeln, dess behörigheter, när den senast användes och om den är Aktiv eller Återkallad.

Behörigheter

Alla nycklar kan anropa endpoints som bara läser. Endpoints som skapar, ändrar eller tar bort något kräver behörigheten write. Exempel är att ringa ett samtal, skicka ett meddelande, boka en tid eller uppdatera en assistent. Referensen på /docs markerar dessa endpoints. En nyckel utan write får ett 403-fel på dem.

Ge varje system den minsta behörighet det behöver. En rapportpanel behöver bara read.

Återkalla en nyckel

1. På Utvecklare hittar du nyckeln i tabellen API-nycklar.
2. Klicka på Återkalla och bekräfta.

Förfrågningar som använder nyckeln misslyckas omedelbart med 401. Återkallade nycklar finns kvar i listan, markerade Återkallad, så att du kan se historiken. En nyckel kan inte redigeras: för att ändra dess behörigheter skapar du en ny nyckel och återkallar den gamla.

Göra förfrågningar

• Bas-URL: https://ringhum.com/api/v1
• Autentisering: skicka nyckeln som en Bearer-token: Authorization: Bearer ck_live_…
• Format: JSON in och ut. Skicka Content-Type: application/json med en body.
• Tider är ISO 8601 i UTC. Telefonnummer är E.164, till exempel +14155550132. Id:n är heltal.
• Uppdateringar använder PATCH med bara de fält du vill ändra.
• Varje svar har en X-Request-Id-header. Ange den när du kontaktar supporten.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

För att kontrollera vilken arbetsyta en nyckel tillhör anropar du GET /me.

Svar och sidnumrering

Ett enskilt objekt kommer tillbaka som {"data": {…}}. Listor som är sidnumrerade kommer tillbaka med ett meta-objekt:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

Använd page och per_page för att bläddra genom resultaten. per_page är 25 som standard och kan vara högst 100.

Fel

Alla fel har samma form, med en stabil type du kan kontrollera i din kod:

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

Hastighetsgränser

Du kan göra 120 förfrågningar per minut. Svaren innehåller headers med X-RateLimit-Limit och X-RateLimit-Remaining. När du går över gränsen får du 429 med en Retry-After-header som anger hur många sekunder du ska vänta.

Tips: Fråga inte upprepade gånger efter samtalsresultat. Lägg till en webhook för call.ended så skickar Ringhum sammanfattningen och transkriberingen till dig när samtalet är avslutat. Se Webhooks.

Vanliga frågor

Finns det en maskinläsbar specifikation? Ja. OpenAPI 3.1-beskrivningen finns på /api/v1/openapi.json och kräver ingen nyckel. Du kan generera en klient från den.

Slutar en nyckel fungera om personen som skapade den slutar? Nej. Nycklar tillhör arbetsytan och fortsätter fungera tills de återkallas. Återkalla nycklar du inte längre litar på, särskilt när någon som hade åtkomst slutar.

Kan jag använda API:et från en webbsida? Nej. Vem som helst som öppnar sidan skulle kunna läsa nyckeln. Anropa API:et från din server.