# API-nyckel-API Dessa slutpunkter låter dig hantera ditt kontos API-nycklar via kod. De fungerar alla endast på det anropande kontots egna nycklar. Det finns två typer av nycklar, och de finns på separata sökvägar: - **Din huvudnyckel** — den enda nyckeln med full åtkomst under **Inställningar → Integrationer → API-nyckel**. Slå upp dess maskerade förhandsgranskning, kontrollera din användning av hastighetsbegränsningar, rotera den eller återkalla den. Dessa är slutpunkterna `/api-keys/current`, `/api-keys/rotate` och `/api-keys/usage` nedan. - **Begränsade nycklar (Scoped keys)** — extra, namngivna nycklar som du skapar för en specifik uppgift, var och en begränsad till de delar av API:et som du väljer. Dessa är slutpunkterna `/api-keys` och `/api-keys/{id}` under [Begränsade nycklar](#scoped-keys). Ingenting med din huvudnyckel ändras när du skapar en sådan; befintliga integrationer fortsätter att fungera opåverkade. Alla sökvägar nedan är relativa till API:ets bas-URL: ``` https://api.youraiconnector.com/v1 ``` Varje begäran måste autentiseras. Se [Autentisering](authentication.md) för de fyra accepterade metoderna. Exemplen här använder `X-API-Key`-huvudet (och en form med frågeparameter för cURL). > **Läs detta först.** Att rotera eller återkalla din nyckel träder i kraft **omedelbart**. I samma ögonblick som anropet lyckas slutar den gamla nyckeln att fungera — varje integration som fortfarande använder den börjar få `401`-fel. Planera för detta: rotera under ett underhållsfönster och uppdatera alla dina integrationer direkt. --- ## Hämta metadata för aktuell nyckel Returnerar din aktiva nyckel: hela nyckeln i `api_key` när en hämtningsbar kopia finns, en maskerad förhandsgranskning (första 4 och sista 4 tecknen), och, när tillgängligt, datumet då den skapades. `api_key` är `null` för nycklar som skapades innan hämtningsbara kopior sparades — rotera en gång så kan den nya nyckeln visas igen senare. `GET /api-keys/current` **cURL** ```bash curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/api-keys/current", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` **Svar** ```json { "success": true, "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst", "api_key_masked": "abcd...qrst", "created_at": "2026-06-01T10:00:00.000Z" } ``` Om kontot inte har någon API-nyckel är svaret `404` med `{ "success": false, "error": "No API key found for this account" }`. --- ## Hämta användning av hastighetsbegränsning Returnerar din användning av hastighetsbegränsning för det aktuella fönstret: begäransgränsen per fönster, hur många anrop som har räknats hittills, hur många som återstår och när fönstret återställs. Använd detta för att bygga klient-sidig strypning så att din integration saktar ner innan den träffar `429`-svar. `GET /api-keys/usage` **cURL** ```bash curl "https://api.youraiconnector.com/v1/api-keys/usage" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/usage", { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/api-keys/usage", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` **Svar** ```json { "success": true, "usage": { "limit": 300, "window_seconds": 60, "used": 37, "remaining": 263, "window_resets_at": "2026-06-09T12:01:00.000Z" } } ``` Om inga anrop har registrerats i det aktuella fönstret ännu, rapporteras användningen som noll och svaret inkluderar ett `note`-fält som förklarar varför. --- ## Rotera nyckeln Genererar en ny API-nyckel och ogiltigförklarar den föregående i samma steg. Använd detta om du misstänker att din nyckel har läckt, eller som en del av en policy för regelbunden rotation av inloggningsuppgifter. `POST /api-keys/rotate` > **Den nya nyckeln visas endast en gång.** Den returneras i detta svar och kan inte hämtas i sin helhet i efterhand — lagra den säkert så fort du tar emot den. Den tidigare nyckeln slutar fungera i samma ögonblick som detta anrop lyckas, så uppdatera alla integrationer som använde den. **cURL** ```bash curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); // Save data.api_key now — it will not be shown again. ``` **Python** ```python import requests res = requests.post( "https://api.youraiconnector.com/v1/api-keys/rotate", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() # Save data["api_key"] now — it will not be shown again. ``` **Svar** ```json { "success": true, "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst", "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again." } ``` --- ## Återkalla nyckeln Tar permanent bort ditt kontos API-nyckel. Återkallandet sker omedelbart: varje efterföljande begäran som använder den återkallade nyckeln — inklusive integrationer som Make, Zapier eller anpassade skript — avvisas med ett `401`. För att återställa API-åtkomst efteråt, generera en ny nyckel från dina kontoinställningar medan du är inloggad i appen. `DELETE /api-keys/current` > **Det går inte att ångra.** Till skillnad från rotation ger återkallande dig ingen ersättningsnyckel. Återkalla endast när du avser att stoppa API-åtkomst (till exempel en läckt nyckel som du inte omedelbart kan ersätta). **cURL** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.delete( "https://api.youraiconnector.com/v1/api-keys/current", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` **Svar** ```json { "success": true, "revoked": true, "message": "API key revoked. All requests using it will be rejected immediately." } ``` Om kontot inte har någon nyckel att återkalla är svaret `404`. --- ## Begränsade nycklar En begränsad nyckel är en extra API-nyckel som du skapar för en specifik uppgift, med endast den åtkomst som uppgiften kräver. Det klassiska exemplet: du vill koppla en klientpanel, ett rapportverktyg eller ett internt skript till ditt konto utan att lämna ut en nyckel som också kan skicka meddelanden, ändra dina AI-agenter eller köpa ett telefonnummer. Begränsningen följer med själva nyckeln, så den som innehar den kan bara göra det du tillät när du skapade den. **Vad du kan begränsa** | Fält | Vad det betyder | |---|---| | `read_only` | `true` (standard) innebär att endast läsförfrågningar är tillåtna. Alla skapande-, uppdaterings- eller raderingsförfrågningar nekas. | | `tags` | Listan över API-sektioner som nyckeln får använda, skrivna med samma sektionsnamn som du ser i dessa dokument och i [API-utforskaren](reference.md) — `Analytics`, `Campaigns`, `Contacts`, `Messages`, `Appointments`, och så vidare. En tom lista innebär alla sektioner. | | `sub_account_ids` | Vilka hanterade konton nyckeln får agera på. Tomt innebär endast ditt eget konto; `["*"]` innebär alla konton som du faktiskt hanterar. Ägandeskap kontrolleras fortfarande vid varje förfrågan. | | `rate_limit_per_min` | Förfrågningar per minut för denna nyckel, räknat i dess egen budget så att den inte kan förbruka dina andra integrationers tilldelning. Standardvärdet är `60` och kan inte sättas högre än `300`. | Du kan också ge en nyckel ett `expires_at`-datum (ISO 8601, och det måste vara i framtiden). Efter den tidpunkten slutar nyckeln att fungera av sig själv. Utelämna detta så upphör nyckeln aldrig att gälla förrän du återkallar den. > **Nekanden misslyckas stängt.** Om en förfrågan faller utanför vad nyckeln tillåter, nekas den istället för att släppas igenom: en skrivning med en skrivskyddad nyckel returnerar `403` med `error_code: "key_read_only"`, och allt utanför nyckelns tillåtna sektioner returnerar `403` med `error_code: "key_scope_denied"`. Om en begränsad nyckel får ett oväntat `403`, är slutpunkten du anropade helt enkelt inte inom dess omfattning — utöka nyckelns behörighet eller använd din huvudnyckel. > **Endast kontoägaren hanterar nycklar.** Dessa fyra slutpunkter kräver din huvudnyckel eller en ägarsession i appen. En begränsad nyckel kan aldrig lista, skapa, redigera eller återkalla nycklar — inklusive sig själv — så en begränsad nyckel kan aldrig användas för att skapa en mer omfattande nyckel. Försök returnerar `403` med `error_code: "key_scope_denied"`. Av samma anledning är `API Keys` inte en sektion du kan bevilja: att be om den returnerar `400` med `error_code: "invalid_scopes"`. ### Lista begränsade nycklar Returnerar kontots begränsade nycklar, de nyaste först (upp till 200), inklusive återkallade så att du kan se vad som drogs tillbaka och när. Endast maskerade förhandsgranskningar returneras — en begränsad nyckels värde visas en gång, vid skapandet, och kan aldrig hämtas i efterhand. `GET /api-keys` **cURL** ```bash curl "https://api.youraiconnector.com/v1/api-keys" \ -H "X-API-Key: YOUR_API_KEY" ``` **Svar** ```json { "success": true, "api_keys": [ { "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "label": "Client dashboard - Acme", "key_preview": "abcd...qrst", "scopes": { "read_only": true, "tags": ["Analytics"], "sub_account_ids": [], "rate_limit_per_min": 60 }, "expires_at": null, "last_used_at": "2026-08-20T14:03:00.000Z", "created_at": "2026-08-14T09:12:00.000Z", "revoked_at": null, "revoked": false } ] } ``` ### Skapa en begränsad nyckel Skapar en ny begränsad nyckel och returnerar dess värde **en gång**. `POST /api-keys` > **Nyckeln visas endast en gång.** Den finns i detta svar och ingen annanstans, någonsin — det finns inget sätt att slå upp den igen efteråt. Spara den så fort du tar emot den. Om du tappar bort den, återkalla den och skapa en ny. **Brödtextfält** — alla är valfria: | Fält | Typ | Anteckningar | |---|---|---| | `label` | string | Ditt eget namn för nyckeln, visas i listan och under Inställningar. | | `scopes` | object | De fyra fälten i tabellen ovan. Utelämna hela objektet för att få säkra standardinställningar: skrivskyddad, begränsad till `Analytics`, endast ditt eget konto, 60 förfrågningar per minut. | | `expires_at` | ISO 8601-datum | Valfritt utgångsdatum, måste vara i framtiden. | **cURL** ```bash curl -X POST "https://api.youraiconnector.com/v1/api-keys" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Client dashboard - Acme", "scopes": { "read_only": true, "tags": ["Analytics"], "sub_account_ids": [], "rate_limit_per_min": 60 } }' ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ label: "Client dashboard - Acme", scopes: { read_only: true, tags: ["Analytics"] }, }), }); const data = await res.json(); // Save data.api_key now — it will not be shown again. ``` **Python** ```python import requests res = requests.post( "https://api.youraiconnector.com/v1/api-keys", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "label": "Client dashboard - Acme", "scopes": {"read_only": True, "tags": ["Analytics"]}, }, ) data = res.json() # Save data["api_key"] now — it will not be shown again. ``` **Svar** — `201 Created` ```json { "success": true, "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst", "key": { "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "label": "Client dashboard - Acme", "key_preview": "abcd...qrst", "scopes": { "read_only": true, "tags": ["Analytics"], "sub_account_ids": [], "rate_limit_per_min": 60 }, "expires_at": null, "revoked": false }, "message": "Store this key now — it is shown once and cannot be retrieved again." } ``` Ett par detaljer som är bra att känna till när du bygger mot detta: - **Att utelämna `scopes` är inte samma sak som att skicka en tom `tags`-lista.** Lämna `scopes` ute helt för att få säkra standardinställningar (skrivskyddad, endast `Analytics`). Skicka `"tags": []` avsiktligt så kan nyckeln använda varje sektion — det tolkas som en medveten begäran om en obegränsad nyckel. - **`read_only` förblir `true` såvida du inte uttryckligen skickar `false`.** Ett skrivfel eller en saknad flagga kan aldrig av misstag skapa en nyckel som kan skriva. ### Uppdatera en begränsad nyckel Ändrar en nyckels etikett, omfattning (scopes) och/eller utgångsdatum. Skicka valfri kombination av de tre; om ingen skickas returneras `400`. `PATCH /api-keys/{id}` `{id}` är nyckelns `id` från listan (värdet `key_...`), aldrig själva nyckeln. > **Omfattningar (scopes) ersätts, inte sammanfogas.** Det du skickar blir nyckelns fullständiga behörighetsuppsättning. Detta är avsiktligt: att begränsa en nyckel kan aldrig tyst lämna kvar den gamla, bredare åtkomsten. Skicka alltid hela `scopes`-objektet du vill ha, inte bara det fält du ändrar. Nyckelns värde ändras aldrig. Det finns ingen rotering på plats för en begränsad nyckel — för att byta ut en, skapa en ny nyckel och återkalla den gamla, så att en autentiseringsuppgifts åtkomst aldrig kan ändras under en integration som fortfarande använder den. **cURL** ```bash curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Client dashboard - Acme (read-only)", "scopes": { "read_only": true, "tags": ["Analytics", "Campaigns"], "sub_account_ids": [], "rate_limit_per_min": 30 } }' ``` **Svar** ```json { "success": true, "key": { "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "label": "Client dashboard - Acme (read-only)", "key_preview": "abcd...qrst", "scopes": { "read_only": true, "tags": ["Analytics", "Campaigns"], "sub_account_ids": [], "rate_limit_per_min": 30 }, "expires_at": null, "last_used_at": "2026-08-20T14:03:00.000Z", "created_at": "2026-08-14T09:12:00.000Z", "revoked_at": null, "revoked": false } } ``` Om det inte finns någon nyckel med det id:t på ditt konto blir svaret `404`. ### Återkalla en begränsad nyckel Återkallandet sker omedelbart: nästa begäran som använder den nyckeln avvisas med ett `401`. Din huvudnyckel och alla andra begränsade nycklar påverkas inte. `DELETE /api-keys/{id}` Nyckeln stannar kvar i din lista markerad som `"revoked": true`, så att du behåller dokumentationen över vad som funnits och vad den kunde nå. Att återkalla en nyckel som redan är återkallad lyckas och ändrar ingenting. **cURL** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \ -H "X-API-Key: YOUR_API_KEY" ``` **Svar** ```json { "success": true, "revoked": true, "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "message": "API key revoked. All requests using it will be rejected immediately." } ``` --- ## API-nycklar API-fel API-nyckel-slutpunkter returnerar standardfelkuvertet: ```json { "success": false, "error": "No API key found for this account" } ``` På en API-nyckel-slutpunkt returnerar en saknad eller ogiltig nyckel `401` och ett konto utan registrerad nyckel returnerar `404`. De delade koderna som varje slutpunkt kan returnera — `400`, `403` (din plan inkluderar inte API-åtkomst), `429` (hastighetsbegränsning) och `500` — listas med vägledning för återförsök i [Fel & Paginering](errors-and-pagination.md). Slutpunkterna för begränsade nycklar lägger till några namngivna koder i fältet `error_code` så att du kan skilja fallen åt: | `error_code` | Status | Vad hände | |---|---|---| | `key_read_only` | `403` | En skrivskyddad nyckel försökte utföra en skrivåtgärd. | | `key_scope_denied` | `403` | Nyckeln är inte tillåten på den slutpunkten eller det hanterade kontot — eller så försökte en begränsad nyckel hantera API-nycklar, vilket aldrig är tillåtet. | | `invalid_scopes` | `400` | De begärda omfattningarna inkluderade sektionen `API Keys`. Nycklar kan inte hantera nycklar. | | `404` | `404` | Ingen nyckel med det id:t finns på ditt konto. | --- ## Nästa steg - [Autentisering](authentication.md) — de fyra sätten att autentisera en begäran och hur nyckelomfattningar tillämpas. - [Fel och hastighetsbegränsningar](errors-and-pagination.md) — statuskoder och gränsen på 300 förfrågningar/min.