API-nøgler og scopes

Ringhum REST API'et giver dine egne systemer adgang til dit workspace: hent opkald og transskriptioner, opret assistenter, book aftaler, håndter kontakter, foretag udgående opkald og meget mere. Hver anmodning autentificeres med en API-nøgle, der tilhører ét workspace. Denne artikel dækker oprettelse af nøgler og de konventioner, alle endpoints deler. Den fulde endpoint-reference findes på /docs.

Hvem kan administrere nøgler

API'et er tilgængeligt på alle planer. Hvad en nøgle kan gøre, er stadig begrænset af din plan: hvis du for eksempel opretter en assistent ud over din plans grænse, får du en fejl.

Opret en API-nøgle

1. Åbn Udviklere i sidebjælken.
2. I kortet API-nøgler skal du klikke på Opret nøgle.
3. Indtast et Nøglenavn, der siger, hvor nøglen bruges, for eksempel "Produktionsserver".
4. Under Scopes skal du sætte flueben ved read, write eller begge.
5. Klik på Opret nøgle.
6. Kopiér nøglen fra den grønne boks, og gem den et sikkert sted, for eksempel din servers hemmelighedslager. Klik på Færdig.

Vigtigt: Nøglen vises kun én gang. Ringhum gemmer kun et fingeraftryk af den, så den kan ikke vises igen. Hvis du mister den, skal du oprette en ny nøgle og tilbagekalde den gamle.

Nøgler starter med ck_live_. Tabellen API-nøgler viser hver nøgles navn, de første tegn i nøglen, dens scopes, hvornår den sidst blev brugt, og om den er Aktiv eller Tilbagekaldt.

Scopes

Alle nøgler kan kalde endpoints, der kun læser. Endpoints, der opretter, ændrer eller sletter noget, kræver scopet write. Eksempler er at foretage et opkald, sende en besked, booke en aftale eller opdatere en assistent. Referencen på /docs markerer disse endpoints. En nøgle uden write får en 403-fejl på dem.

Giv hvert system den mindste adgang, det har brug for. Et rapporteringsdashboard har kun brug for read.

Tilbagekald en nøgle

1. På Udviklere skal du finde nøglen i tabellen API-nøgler.
2. Klik på Tilbagekald, og bekræft.

Anmodninger, der bruger nøglen, fejler øjeblikkeligt med 401. Tilbagekaldte nøgler forbliver på listen, markeret Tilbagekaldt, så du kan se deres historik. En nøgle kan ikke redigeres: for at ændre dens scopes skal du oprette en ny nøgle og tilbagekalde den gamle.

Sådan foretager du anmodninger

• Base-URL: https://ringhum.com/api/v1
• Autentifikation: send nøglen som et Bearer-token: Authorization: Bearer ck_live_…
• Format: JSON ind og ud. Send Content-Type: application/json med en body.
• Tider er ISO 8601 i UTC. Telefonnumre er E.164, for eksempel +14155550132. Id'er er heltal.
• Opdateringer bruger PATCH med kun de felter, du vil ændre.
• Hvert svar bærer en X-Request-Id-header. Inkludér den, når du kontakter support.

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

For at tjekke, hvilket workspace en nøgle tilhører, kald GET /me.

Svar og paginering

Et enkelt objekt kommer tilbage som {"data": {…}}. Lister, der er pagineret, kommer tilbage med et 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
  }
}

Brug page og per_page til at bevæge dig gennem resultaterne. per_page er som standard 25 og kan højst være 100.

Fejl

Enhver fejl har samme form, med en stabil type, du kan tjekke i din kode:

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

Rate limits

Du kan foretage 120 anmodninger i minuttet. Svar inkluderer headerne X-RateLimit-Limit og X-RateLimit-Remaining. Når du overskrider grænsen, får du 429 med en Retry-After-header, der angiver, hvor mange sekunder du skal vente.

Tip: Undlad at polle efter opkaldsresultater. Tilføj en webhook til call.ended, så sender Ringhum opsummeringen og transskriptionen til dig, når opkaldet er afsluttet. Se Webhooks.

Ofte stillede spørgsmål

Findes der en maskinlæsbar spec? Ja. OpenAPI 3.1-beskrivelsen findes på /api/v1/openapi.json og kræver ingen nøgle. Du kan generere en klient ud fra den.

Stopper en nøgle med at virke, hvis personen, der oprettede den, forlader virksomheden? Nej. Nøgler tilhører workspacet og bliver ved med at virke, indtil de tilbagekaldes. Tilbagekald nøgler, du ikke længere stoler på, især når nogen med adgang forlader virksomheden.

Kan jeg bruge API'et fra en webside? Nej. Alle, der åbner siden, kan læse nøglen. Kald API'et fra din server.