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. 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 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

curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Svar

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

curl "https://api.youraiconnector.com/v1/api-keys/usage" \
  -H "X-API-Key: YOUR_API_KEY"

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/usage",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Svar

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

curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"

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

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

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

curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \
  -H "X-API-Key: YOUR_API_KEY"

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

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Svar

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

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

curl "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY"

Svar

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

cURL

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

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

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

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

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

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

curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY"

Svar

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

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

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:

Nästa steg #

• Autentisering — de fyra sätten att autentisera en begäran och hur nyckelomfattningar tillämpas.
• Fel och hastighetsbegränsningar — statuskoder och gränsen på 300 förfrågningar/min.