# API-nøgle-API Disse slutpunkter lader dig administrere din kontos API-nøgler via kode. De opererer alle kun på den kaldende kontos egne nøgler. Der findes to typer nøgler, og de findes på separate stier: - **Din hovednøgle** — den enkelte nøgle med fuld adgang under **Indstillinger → Integrationer → API-nøgle**. Slå dens maskerede forhåndsvisning op, tjek dit forbrug af hastighedsbegrænsning, roter den eller tilbagekald den. Dette er `/api-keys/current`, `/api-keys/rotate` og `/api-keys/usage` slutpunkterne nedenfor. - **Omfangsbegrænsede nøgler** — ekstra, navngivne nøgler, som du opretter til en specifik opgave, hver især begrænset til de dele af API'et, du vælger. Dette er `/api-keys` og `/api-keys/{id}` slutpunkterne under [Omfangsbegrænsede nøgler](#scoped-keys). Intet ved din hovednøgle ændres, når du opretter en; eksisterende integrationer fortsætter uberørt. Alle stier herunder er relative til API'ets base-URL: ``` https://api.youraiconnector.com/v1 ``` Enhver anmodning skal godkendes. Se [Godkendelse](authentication.md) for de fire accepterede metoder. Eksemplerne her bruger `X-API-Key`-headeren (og én forespørgselsparameter-form til cURL). > **Læs dette først.** Roterende eller tilbagekaldelse af din nøgle træder i kraft **øjeblikkeligt**. I det øjeblik et af disse kald lykkes, holder den gamle nøgle op med at virke — enhver integration, der stadig bruger den, begynder at modtage `401`-fejl. Planlæg det: roter i et vedligeholdelsesvindue og opdater alle dine integrationer med det samme. --- ## Hent aktuelle nøglemetadata Returnerer din aktive nøgle: den fulde nøgle i `api_key`, når en kopi, der kan hentes, findes, et maskeret eksempel (første 4 og sidste 4 tegn), og når tilgængelig, datoen for oprettelsen. `api_key` er `null` for nøgler oprettet før kopier, der kan hentes, blev gemt — roter én gang, og den nye nøgle kan vises igen senere. `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" } ``` Hvis kontoen ikke har nogen API-nøgle, er svaret `404` med `{ "success": false, "error": "No API key found for this account" }`. --- ## Hent forbrug af hastighedsbegrænsning Returnerer dit forbrug af hastighedsbegrænsning for det aktuelle vindue: anmodningsgrænsen pr. vindue, hvor mange anmodninger der er talt indtil videre, hvor mange der er tilbage, og hvornår vinduet nulstilles. Brug dette til at bygge klient-side throttling, så din integration drosler ned, før den rammer `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" } } ``` Hvis der endnu ikke er registreret nogen anmodninger i det aktuelle vindue, rapporteres forbruget som nul, og svaret inkluderer et `note`-felt, der forklarer hvorfor. --- ## Roter nøglen Genererer en ny API-nøgle og ugyldiggør den forrige i samme trin. Brug dette, hvis du har mistanke om, at din nøgle er lækket, eller som en del af en regelmæssig politik for rotation af legitimationsoplysninger. `POST /api-keys/rotate` > **Den nye nøgle vises kun én gang.** Den returneres i dette svar og kan ikke hentes i sin helhed efterfølgende – gem den sikkert i det øjeblik, du modtager den. Den forrige nøgle holder op med at fungere, så snart dette kald lykkes, så opdater alle integrationer, der brugte 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." } ``` --- ## Tilbagekald nøglen Sletter permanent din kontos API-nøgle. Tilbagekaldelse sker øjeblikkeligt: enhver efterfølgende anmodning, der bruger den tilbagekaldte nøgle – inklusive integrationer som Make, Zapier eller brugerdefinerede scripts – afvises med en `401`. For at gendanne API-adgang bagefter skal du generere en ny nøgle fra dine kontoindstillinger, mens du er logget ind i appen. `DELETE /api-keys/current` > **Der er ingen fortrydelsesmulighed.** I modsætning til rotation giver tilbagekaldelse dig ikke en erstatningsnøgle. Tilbagekald kun, når du har til hensigt at stoppe API-adgangen (for eksempel en lækket nøgle, som du ikke umiddelbart kan erstatte). **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." } ``` Hvis kontoen ikke har nogen nøgle at tilbagekalde, er svaret `404`. --- ## Omfangsbegrænsede nøgler En omfangsbegrænset nøgle er en ekstra API-nøgle, du opretter til en specifik opgave, som kun har den adgang, opgaven kræver. Det klassiske eksempel: Du vil forbinde et klient-dashboard, et rapporteringsværktøj eller et internt script til din konto uden at udlevere en nøgle, der også kan sende beskeder, ændre dine AI-agenter eller købe et telefonnummer. Begrænsningen følger selve nøglen, så den, der besidder den, kun kan gøre det, du tillod, da du oprettede den. **Hvad du kan begrænse** | Felt | Hvad det betyder | |---|---| | `read_only` | `true` (standard) betyder, at kun læseanmodninger er tilladt. Enhver oprettelse, opdatering eller sletning afvises. | | `tags` | Listen over API-sektioner, som nøglen må bruge, skrevet med de samme sektionsnavne, som du ser i disse dokumenter og i [API-udforskeren](reference.md) — `Analytics`, `Campaigns`, `Contacts`, `Messages`, `Appointments` osv. En tom liste betyder alle sektioner. | | `sub_account_ids` | Hvilke administrerede konti nøglen må handle på. Tom betyder kun din egen konto; `["*"]` betyder enhver konto, du rent faktisk administrerer. Ejerskab tjekkes stadig ved hver anmodning. | | `rate_limit_per_min` | Anmodninger pr. minut for denne nøgle, talt i sit eget budget, så den ikke kan opbruge dine andre integrationers kvote. Standard er `60` og kan ikke sættes højere end `300`. | Du kan også give en nøgle en `expires_at` dato (ISO 8601, og den skal være i fremtiden). Efter det tidspunkt holder nøglen op med at virke af sig selv. Udelad den, og nøglen udløber aldrig, før du tilbagekalder den. > **Afvisninger fejler lukket.** Hvis en anmodning falder uden for det, nøglen tillader, afvises den i stedet for at blive gennemført: en skrivning med en skrivebeskyttet nøgle returnerer `403` med `error_code: "key_read_only"`, og alt uden for nøglens tilladte sektioner returnerer `403` med `error_code: "key_scope_denied"`. Hvis en omfangsbegrænset nøgle får en uventet `403`, er det slutpunkt, du kaldte, simpelthen ikke inden for dens omfang — udvid nøglen eller brug din hovednøgle. > **Kun kontoejeren administrerer nøgler.** Disse fire slutpunkter kræver din hovednøgle eller en ejersession i appen. En omfangsbegrænset nøgle kan aldrig liste, oprette, redigere eller tilbagekalde nøgler — inklusive sig selv — så en begrænset nøgle kan aldrig bruges til at oprette en mere omfattende nøgle. Forsøg returnerer `403` med `error_code: "key_scope_denied"`. Af samme årsag er `API Keys` ikke en sektion, du kan give adgang til: anmodning om den returnerer `400` med `error_code: "invalid_scopes"`. ### Liste over omfangsbegrænsede nøgler Returnerer kontoens omfangsbegrænsede nøgler, nyeste først (op til 200), inklusive tilbagekaldte, så du kan se, hvad der blev trukket tilbage og hvornår. Kun maskerede forhåndsvisninger returneres — en omfangsbegrænset nøgles værdi vises én gang ved oprettelse og kan aldrig hentes efterfølgende. `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 } ] } ``` ### Opret en omfangsbegrænset nøgle Opretter en ny scoped nøgle og returnerer dens værdi **én gang**. `POST /api-keys` > **Nøglen vises kun én gang.** Den findes i dette svar og aldrig andre steder — der er ingen måde at slå den op igen bagefter. Gem den i det øjeblik, du modtager den. Hvis du mister den, skal du tilbagekalde den og oprette en ny. **Brødtekstfelter** — alle valgfrie: | Felt | Type | Noter | |---|---|---| | `label` | string | Dit eget navn til nøglen, som vises på listen og i Indstillinger. | | `scopes` | object | De fire felter i tabellen ovenfor. Udelad hele objektet for at få standardindstillingen: skrivebeskyttet, begrænset til `Analytics`, kun din egen konto, 60 anmodninger pr. minut. | | `expires_at` | ISO 8601 date | Valgfri udløbsdato, skal være i fremtiden. | **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." } ``` Et par detaljer, der er værd at vide, når du bygger mod dette: - **At udelade `scopes` er ikke det samme som at sende en tom `tags` liste.** Udelad `scopes` helt for at få standardindstillingen (kun skrivebeskyttet, `Analytics`). Send `"tags": []` med vilje, og nøglen kan bruge alle sektioner — det læses som en bevidst anmodning om en ubegrænset nøgle. - **`read_only` forbliver `true`, medmindre du eksplicit sender `false`.** En slåfejl eller et manglende flag kan aldrig ved et uheld producere en nøgle, der kan skrive. ### Opdater en scoped nøgle Ændrer en nøgles etiket, scopes og/eller udløbsdato. Send en hvilken som helst kombination af de tre; hvis ingen af dem sendes, returneres `400`. `PATCH /api-keys/{id}` `{id}` er nøglens `id` fra listen (værdien `key_...`), aldrig selve nøglen. > **Scopes erstattes, ikke flettes.** Alt, hvad du sender, bliver nøglens komplette tilladelsessæt. Det er bevidst: indsnævring af en nøgle kan aldrig lydløst efterlade den gamle, bredere adgang. Send altid det fulde `scopes` objekt, du ønsker, ikke kun det felt, du ændrer. Nøglens værdi ændres aldrig. Der findes ingen "rotate-in-place" for en scoped nøgle — for at rotere en, skal du oprette en ny nøgle og tilbagekalde den gamle, så en legitimationsadgang aldrig kan ændre sig under en integration, der stadig holder 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 } } ``` Hvis der ikke er nogen nøgle med det id på din konto, er svaret `404`. ### Tilbagekald en begrænset nøgle Tilbagekaldelsen sker øjeblikkeligt: den næste anmodning, der bruger den nøgle, afvises med en `401`. Din hovednøgle og alle andre begrænsede nøgler påvirkes ikke. `DELETE /api-keys/{id}` Nøglen forbliver på din liste markeret som `"revoked": true`, så du bevarer overblikket over, hvad der eksisterede, og hvad den kunne få adgang til. Tilbagekaldelse af en nøgle, der allerede er tilbagekaldt, gennemføres uden at ændre noget. **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-nøgle-API-fejl API-nøgle-slutpunkter returnerer standardfejl-konvolutten: ```json { "success": false, "error": "No API key found for this account" } ``` På et API-nøgle-slutpunkt returnerer en manglende eller ugyldig nøgle `401`, og en konto uden en registreret nøgle returnerer `404`. De delte koder, som ethvert slutpunkt kan returnere — `400`, `403` (din plan inkluderer ikke API-adgang), `429` (hastighedsbegrænsning) og `500` — er angivet med vejledning om genforsøg i [Fejl & Sidetal](errors-and-pagination.md). Slutpunkterne for begrænsede nøgler tilføjer et par navngivne koder i feltet `error_code`, så du kan skelne mellem tilfældene: | `error_code` | Status | Hvad skete der | |---|---|---| | `key_read_only` | `403` | En skrivebeskyttet nøgle forsøgte at udføre en skrivning. | | `key_scope_denied` | `403` | Nøglen er ikke tilladt på det slutpunkt eller den administrerede konto — eller en begrænset nøgle forsøgte at administrere API-nøgler, hvilket aldrig er tilladt. | | `invalid_scopes` | `400` | De anmodede scopes inkluderede sektionen `API Keys`. Nøgler kan ikke administrere nøgler. | | `404` | `404` | Ingen nøgle med det id på din konto. | --- ## Næste skridt - [Godkendelse](authentication.md) — de fire måder at godkende en anmodning på, og hvordan nøgle-scopes håndhæves. - [Fejl og hastighedsbegrænsninger](errors-and-pagination.md) — statuskoder og grænsen på 300 anmodninger/min.