KEPLIN Docs

API:er & GraphQL API-nycklar

API-nycklar

Generera, avgränsa och återkalla API-nycklar — externa systems åtkomst till dina appars GraphQL.

Externa system — ett ERP som synkroniserar kunder, en webbplats som skapar beställningar, en faktureringsintegration — anropar apparnas GraphQL med en API-nyckel: en hemlighet som skickas i headern x-api-key i varje begäran. Nycklarna hanteras på plattformsnivå och är delade mellan appar: varje nyckel har ett scope — du väljer apparna och, per app, alla endpoints eller bara några. En faktureringsintegration kan till exempel läsa konton i appen Kundhantering och skriva dokument i en annan app, med en enda nyckel.

Nota

Nycklarna tillhör den som administrerar plattformen: sidan API-nycklar är bara tillgänglig för administratörskonton.

Sidan API-nycklar

Öppna menyn API-nycklar i den globala navigeringen. Listan visar alla nycklar på plattformen:

Kolumn Vad det är
Namn Namnet du gav nyckeln — det identifierar integrationen.
Prefix Nyckelns första tecken (t.ex. amk_A1b2C3…) — de finns för att du ska känna igen vilken som är vilken utan att någonsin visa hela nyckeln.
Scope Apparna den ger åtkomst till och, per app, ”alla endpoints” eller listan över de beviljade.
Status aktivt eller återkallad.
Senast använd När nyckeln senast användes — aldrig, om den inte har använts.

Sidan API-nycklar, med varje nyckels scope och senaste användning.
Sidan API-nycklar, med varje nyckels scope och senaste användning.

Dica

Kolumnen Senast använd är ditt städverktyg: en nyckel som inte använts i månader är en kandidat för återkallelse.

Skapa en API-nyckel

  1. Tryck på Ny API-nyckel.
  2. Ge den ett Nyckelns namn — t.ex. faktureringsintegration.
  3. Markera apparna som ska ingå under Scope — tillåtna appar och endpoints. Som standard beviljar varje markerad app ”Alla endpoints i den här appen.”
  4. För att strama åt åtkomsten i en app: markera Begränsa till specifika endpoints och välj API:erna ett i taget. I ett Tabell-API täcker beviljandet alla aktiva operationer — listan visar ”ger åtkomst till: getContas, addContas, …” så att du vet exakt vad du beviljar.
  5. Tryck på Generera API-nyckel.

Modalen för att skapa en API-nyckel, med scope per app och endpoint.
Modalen för att skapa en API-nyckel, med scope per app och endpoint.

Kopiera och förvara nyckeln

Efter genereringen visar fönstret Nyckeln i klartext — en enda gång. Kopiera den med Kopiera och förvara den på ett säkert ställe (en hemlighetshanterare, ditt teams valv). När du stänger fönstret ser du den inte igen — plattformen sparar inte nyckeln i klartext; om du tappar bort den kan du bara återkalla den och generera en ny.

Den genererade nyckeln, i klartext för den enda gången, med knappen Kopiera.
Den genererade nyckeln, i klartext för den enda gången, med knappen Kopiera.

Atenção

Behandla nyckeln som ett lösenord: lägg den inte i källkod, inte i URL:er, inte på användarskärmar. Om du misstänker en läcka: återkalla direkt — att generera en ny nyckel tar sekunder.

Använda nyckeln

Nyckeln skickas i headern x-api-key i varje begäran till appens GraphQL-endpoint:

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

Fliken Dokumentation i varje API genererar det här exemplet (och JavaScript-varianten) redan med rätt operation — bara din nyckel fattas.

Vad en nyckel ser och inte ser:

  • Bara publicerade API:er — aldrig utkast, inte ens med hela appen i scope.
  • Bara det som scopet beviljar: att anropa en app utanför scopet ger 403 — API key not authorised for this project; att anropa en endpoint utanför scopet, 403 — API key not authorised for this endpoint.
  • Alltid appens huvudversion (eller den publicerade versionen för den adress som används) — aldrig en developers arbetsversion.

Gränser och fel

Varje nyckel har ett tak för antal begäranden per minut. De felsvar som en integration bör kunna hantera:

Svar Betydelse Vad du gör
401 Nyckeln saknas, är ogiltig, har gått ut eller är återkallad. Kontrollera headern och nyckelns status i listan.
403 Nyckeln är giltig men saknar åtkomst till appen eller endpointen. Justera scopet — generera en ny nyckel med rätt scope.
429 Taket för antal begäranden per minut är nått. Vänta den tid som anges i headern retry-after och försök igen.

Återkalla en nyckel

  1. Tryck på återkallelseikonen på radens i listan.
  2. Bekräfta med Återkalla nyckel.

Återkallelsen sker omedelbart: alla appar som använder nyckeln förlorar åtkomsten vid nästa begäran. En återkallad nyckel kan inte aktiveras igen — den ligger kvar i listan, märkt återkallad, som en notering.

Varför inte…?

  • Jag tappade bort nyckeln — kan jag se den igen? Nej. Nyckeln i klartext visas bara i det ögonblick den skapas. Återkalla den gamla och generera en ny.
  • Jag måste ge åtkomst till en endpoint till — redigerar jag nyckeln? Scopet anges när nyckeln skapas. Generera en ny nyckel med det fullständiga scopet, byt ut den i integrationen och återkalla den gamla.
  • Varför får integrationen 403 på en ny endpoint? Nyckeln begränsades till specifika endpoints och den nya finns inte i listan — samma botemedel: en ny nyckel med rätt scope.
  • Ger nyckeln åtkomst till appens skärmar? Nej. En nyckel talar bara med GraphQL-endpointen. Appanvändarnas konton är något annat, och de hanteras i själva appens inställningar.