API-sleutels en scopes

Met de Ringhum REST API kunnen je eigen systemen met je werkruimte werken: gesprekken en transcripten opvragen, assistenten aanmaken, afspraken boeken, contacten beheren, uitgaande gesprekken plaatsen en meer. Elk verzoek wordt geauthenticeerd met een API-sleutel die bij één werkruimte hoort. Dit artikel behandelt het aanmaken van sleutels en de conventies die elk endpoint deelt. De volledige endpoint-referentie staat op /docs.

Wie sleutels kan beheren

De API is beschikbaar op elk abonnement. Wat een sleutel kan doen, wordt nog steeds beperkt door je abonnement: het aanmaken van een assistent boven de limiet van je abonnement geeft bijvoorbeeld een foutmelding.

Een API-sleutel aanmaken

1. Open Ontwikkelaars in de zijbalk.
2. Klik in het kaartje API-sleutels op Sleutel aanmaken.
3. Voer een Naam van de sleutel in die aangeeft waar de sleutel wordt gebruikt, bijvoorbeeld "Productieserver".
4. Vink onder Scopes read, write of beide aan.
5. Klik op Sleutel aanmaken.
6. Kopieer de sleutel uit het groene vak en bewaar hem op een veilige plek, zoals de secretstore van je server. Klik op Klaar.

Belangrijk: De sleutel wordt maar één keer getoond. Ringhum bewaart alleen een vingerafdruk ervan, dus hij kan niet opnieuw worden getoond. Als je hem kwijtraakt, maak dan een nieuwe sleutel aan en trek de oude in.

Sleutels beginnen met ck_live_. De tabel API-sleutels toont van elke sleutel de naam, de eerste tekens van de sleutel, zijn scopes, wanneer hij voor het laatst is gebruikt en of hij Actief of Ingetrokken is.

Scopes

Elke sleutel kan de endpoints aanroepen die alleen lezen. Endpoints die iets aanmaken, wijzigen of verwijderen hebben de scope write nodig. Voorbeelden zijn een gesprek plaatsen, een bericht versturen, een afspraak boeken of een assistent bijwerken. De referentie op /docs markeert deze endpoints. Een sleutel zonder write krijgt hierop een 403-foutmelding.

Geef elk systeem de kleinst mogelijke toegang die het nodig heeft. Een rapportagedashboard heeft alleen read nodig.

Een sleutel intrekken

1. Zoek op Ontwikkelaars de sleutel in de tabel API-sleutels.
2. Klik op Intrekken en bevestig.

Verzoeken met de sleutel mislukken meteen met 401. Ingetrokken sleutels blijven in de lijst staan, gemarkeerd als Ingetrokken, zodat je hun geschiedenis kunt zien. Een sleutel kan niet worden bewerkt: om de scopes te wijzigen, maak je een nieuwe sleutel aan en trek je de oude in.

Verzoeken doen

• Basis-URL: https://ringhum.com/api/v1
• Authenticatie: stuur de sleutel als Bearer-token: Authorization: Bearer ck_live_…
• Formaat: JSON in en uit. Stuur Content-Type: application/json mee met een body.
• Tijden zijn ISO 8601 in UTC. Telefoonnummers zijn E.164, bijvoorbeeld +14155550132. Id's zijn gehele getallen.
• Updates gebruiken PATCH met alleen de velden die je wilt wijzigen.
• Elke response bevat een X-Request-Id-header. Vermeld deze wanneer je contact opneemt met support.

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

Om te controleren bij welke werkruimte een sleutel hoort, roep je GET /me aan.

Responses en paginering

Een los object komt terug als {"data": {…}}. Lijsten die gepagineerd zijn, komen terug met een meta-object:

{
  "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
  }
}

Gebruik page en per_page om door de resultaten te bladeren. per_page staat standaard op 25 en kan maximaal 100 zijn.

Fouten

Elke fout heeft dezelfde vorm, met een stabiel type dat je in je code kunt controleren:

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

Snelheidslimieten

Je kunt 120 verzoeken per minuut doen. Responses bevatten de headers X-RateLimit-Limit en X-RateLimit-Remaining. Als je over de limiet gaat, krijg je een 429 met een Retry-After-header die aangeeft hoeveel seconden je moet wachten.

Tip: Poll niet voor gespreksresultaten. Voeg een webhook toe voor call.ended en Ringhum stuurt je de samenvatting en het transcript zodra het gesprek is afgelopen. Zie Webhooks.

Veelgestelde vragen

Is er een machineleesbare specificatie? Ja. De OpenAPI 3.1-beschrijving staat op /api/v1/openapi.json en vereist geen sleutel. Je kunt er een client uit genereren.

Stopt een sleutel met werken als de persoon die hem heeft aangemaakt vertrekt? Nee. Sleutels horen bij de werkruimte en blijven werken tot ze worden ingetrokken. Trek sleutels in die je niet meer vertrouwt, vooral wanneer iemand met toegang vertrekt.

Kan ik de API vanaf een webpagina gebruiken? Nee. Iedereen die de pagina opent, zou de sleutel kunnen lezen. Roep de API aan vanaf je server.