KEPLIN Docs

API-er og GraphQL API-nøkler

API-nøkler

Generere, avgrense og tilbakekalle API-nøkler — de eksterne systemenes tilgang til GraphQL i appene dine.

Eksterne systemer — et ERP som synkroniserer kunder, et nettsted som oppretter bestillinger, en faktureringsintegrasjon — kaller GraphQL i appene med en API-nøkkel: en hemmelighet som sendes i headeren x-api-key i hver forespørsel. Nøklene administreres på plattformnivå og deles mellom apper: hver nøkkel har et scope — du velger appene og, per app, alle endepunktene eller bare noen. En faktureringsintegrasjon kan, for eksempel, lese kontoer i appen Kundehåndtering og skrive dokumenter i en annen app, med én enkelt nøkkel.

Nota

Nøklene tilhører den som administrerer plattformen: siden API-nøkler er bare tilgjengelig for administratorkontoer.

Siden API-nøkler

Åpne menyen API-nøkler i den globale navigasjonen. Listen viser alle nøklene på plattformen:

Kolonne Hva det er
Navn Navnet du ga nøkkelen — identifiserer integrasjonen.
Prefiks De første tegnene i nøkkelen (f.eks. amk_A1b2C3…) — de gjør at du kjenner igjen hvilken som er hvilken uten noensinne å vise hele nøkkelen.
Scope Appene den gir tilgang til og, per app, «alle endepunkter» eller listen over de tildelte.
Status aktiv eller tilbakekalt.
Sist brukt Når nøkkelen sist ble brukt — aldri, hvis den ennå ikke har vært det.

Siden API-nøkler, med scope og siste bruk for hver nøkkel.
Siden API-nøkler, med scope og siste bruk for hver nøkkel.

Dica

Kolonnen Sist brukt er ryddeverktøyet ditt: en nøkkel som har gått måneder uten bruk, er en kandidat for tilbakekalling.

Lage en API-nøkkel

  1. Trykk på Ny API-nøkkel.
  2. Gi den et Navn på nøkkelen — f.eks. fakturering-integrasjon.
  3. Under Scope — tillatte apper og endepunkter, merk av appene som skal med. Som standard gir hver avmerket app «Alle endepunkter i denne appen.»
  4. For å stramme inn tilgangen i en app, merk av Begrens til bestemte endepunkter og velg API-ene ett for ett. I et Tabell-API dekker tildelingen alle de aktive operasjonene — listen viser «gir tilgang til: getContas, addContas, …» så du vet nøyaktig hva du gir.
  5. Trykk på Generer API-nøkkel.

Vinduet for å lage en API-nøkkel, med scope per app og endepunkt.
Vinduet for å lage en API-nøkkel, med scope per app og endepunkt.

Kopiere og oppbevare nøkkelen

Etter genereringen viser vinduet Nøkkel-en i klartekst — én eneste gang. Kopier den med Kopier og oppbevar den på et trygt sted (en hemmelighetsforvalter, hvelvet til teamet ditt). Når du lukker vinduet, får du aldri se den igjen — plattformen lagrer ikke nøkkelen i klartekst; mister du den, kan du bare tilbakekalle den og generere en ny.

Nøkkelen generert, i klartekst for den ene gangen, med knappen Kopier.
Nøkkelen generert, i klartekst for den ene gangen, med knappen Kopier.

Atenção

Behandle nøkkelen som et passord: ikke legg den i kildekode, i URL-er eller på brukerskjermer. Mistenker du en lekkasje, tilbakekall med én gang — å generere en ny nøkkel koster sekunder.

Bruke nøkkelen

Nøkkelen følger i headeren x-api-key i hver forespørsel til appens GraphQL-endepunkt:

curl -X POST 'https://o-teu-host/api/graphql/gestao-clientes' \
  -H 'content-type: application/json' \
  -H 'x-api-key: amk_………' \
  -d '{"query":"query { getContas(take: 5) { id nome } }"}'

Fanen Dokumentasjon i hvert API genererer dette eksempelet (og JavaScript-varianten) med riktig operasjon — bare nøkkelen din mangler.

Hva en nøkkel ser og ikke ser:

  • Bare publiserte API-er — utkast aldri, selv med scope for hele appen.
  • Bare det scopet gir: å kalle en app utenfor scopet returnerer 403 — API key not authorised for this project; å kalle et endepunkt utenfor scopet, 403 — API key not authorised for this endpoint.
  • Alltid hovedversjonen av appen (eller den publiserte versjonen for adressen som brukes) — aldri arbeidsversjonen til en developer.

Grenser og feil

Hver nøkkel har et tak på forespørsler per minutt. Feilsvarene som en integrasjon bør vite å håndtere:

Svar Betydning Hva du gjør
401 Nøkkel mangler, er ugyldig, utløpt eller tilbakekalt. Sjekk headeren og statusen til nøkkelen i listen.
403 Gyldig nøkkel, men uten tilgang til appen eller endepunktet. Juster scopet — generer en ny nøkkel med riktig scope.
429 Taket på forespørsler per minutt er nådd. Vent tiden angitt i headeren retry-after og prøv igjen.

Tilbakekalle en nøkkel

  1. I listen, trykk på tilbakekallingsikonet på linjen.
  2. Bekreft med Tilbakekall nøkkel.

Tilbakekallingen er umiddelbar: alle appene som bruker denne nøkkelen, mister tilgangen ved neste forespørsel. En tilbakekalt nøkkel kan ikke aktiveres igjen — den blir stående i listen, merket tilbakekalt, som dokumentasjon.

Hvorfor kan jeg ikke…?

  • Jeg mistet nøkkelen — kan jeg se den igjen? Nei. Nøkkelen i klartekst vises bare i det øyeblikket den opprettes. Tilbakekall den gamle og generer en ny.
  • Jeg må gi tilgang til ett endepunkt til — redigerer jeg nøkkelen? Scopet defineres ved opprettelsen. Generer en ny nøkkel med det komplette scopet, bytt den ut i integrasjonen og tilbakekall den gamle.
  • Hvorfor får integrasjonen 403 på et nytt endepunkt? Nøkkelen ble begrenset til bestemte endepunkter, og det nye står ikke på listen — samme botemiddel: ny nøkkel med riktig scope.
  • Gir nøkkelen tilgang til skjermene i appen? Nei. En nøkkel snakker bare med GraphQL-endepunktet. Kontoene til brukerne av appen er noe annet, administrert i innstillingene til selve appen.