API-Schlüssel-API

Mit diesen Endpunkten können Sie die API-Schlüssel Ihres Kontos programmgesteuert verwalten. Sie funktionieren ausschließlich für die Schlüssel des aufrufenden Kontos.

Es gibt zwei Arten von Schlüsseln, die sich auf unterschiedlichen Pfaden befinden:

Ihr Hauptschlüssel — der einzelne Schlüssel mit vollem Zugriff unter Einstellungen → Integrationen → API-Schlüssel. Hier können Sie die maskierte Vorschau einsehen, Ihre Ratenbegrenzung prüfen, den Schlüssel rotieren oder widerrufen. Dies betrifft die unten aufgeführten Endpunkte /api-keys/current, /api-keys/rotate und /api-keys/usage.
Bereichsbezogene Schlüssel (Scoped keys) — zusätzliche, benannte Schlüssel, die Sie für eine spezifische Aufgabe erstellen und die jeweils auf die von Ihnen gewählten API-Bereiche beschränkt sind. Dies betrifft die Endpunkte /api-keys und /api-keys/{id} unter Bereichsbezogene Schlüssel. An Ihrem Hauptschlüssel ändert sich nichts, wenn Sie einen solchen Schlüssel erstellen; bestehende Integrationen bleiben unberührt.

Alle unten aufgeführten Pfade sind relativ zur API-Basis-URL:

https://api.youraiconnector.com/v1

Jede Anfrage muss authentifiziert sein. Siehe Authentifizierung für die vier akzeptierten Methoden. Die Beispiele hier verwenden den X-API-Key-Header (und eine Abfrageparameter-Form für cURL).

Bitte zuerst lesen. Das Rotieren oder Widerrufen Ihres Schlüssels wird sofort wirksam. Sobald einer dieser Aufrufe erfolgreich ist, funktioniert der alte Schlüssel nicht mehr – jede Integration, die ihn noch verwendet, erhält daraufhin 401-Fehler. Planen Sie dies entsprechend: Führen Sie die Rotation während eines Wartungsfensters durch und aktualisieren Sie umgehend alle Ihre Integrationen.

Metadaten des aktuellen Schlüssels abrufen

Gibt Ihren aktiven Schlüssel zurück: den vollständigen Schlüssel in api_key, wenn eine abrufbare Kopie existiert, eine maskierte Vorschau (die ersten 4 und die letzten 4 Zeichen) und, falls verfügbar, das Erstellungsdatum. api_key ist null für Schlüssel, die erstellt wurden, bevor abrufbare Kopien gespeichert wurden – rotieren Sie einmal, und der neue Schlüssel kann später wieder angezeigt werden.

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()

Antwort

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "api_key_masked": "abcd...qrst",
  "created_at": "2026-06-01T10:00:00.000Z"
}

Wenn das Konto über keinen API-Schlüssel verfügt, lautet die Antwort 404 mit { "success": false, "error": "No API key found for this account" }.

Ratenbegrenzungsauslastung abrufen

Gibt Ihre Ratenbegrenzungsauslastung für das aktuelle Zeitfenster zurück: das Anfragelimit pro Fenster, wie viele Anfragen bisher gezählt wurden, wie viele verbleiben und wann das Fenster zurückgesetzt wird. Nutzen Sie dies, um clientseitiges Drosseln zu implementieren, damit Ihre Integration die Anfragen reduziert, bevor sie 429-Antworten erhält.

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()

Antwort

{
  "success": true,
  "usage": {
    "limit": 300,
    "window_seconds": 60,
    "used": 37,
    "remaining": 263,
    "window_resets_at": "2026-06-09T12:01:00.000Z"
  }
}

Wenn im aktuellen Zeitfenster noch keine Anfragen aufgezeichnet wurden, wird die Auslastung als null gemeldet und die Antwort enthält ein note-Feld, das den Grund dafür erläutert.

Schlüssel rotieren

Generiert einen neuen API-Schlüssel und macht den vorherigen im selben Schritt ungültig. Verwenden Sie dies, wenn Sie vermuten, dass Ihr Schlüssel kompromittiert wurde, oder als Teil einer Richtlinie zur regelmäßigen Rotation von Anmeldedaten.

POST /api-keys/rotate

Der neue Schlüssel wird nur einmal angezeigt. Er wird in dieser Antwort zurückgegeben und kann danach nicht mehr vollständig abgerufen werden – speichern Sie ihn sicher, sobald Sie ihn erhalten. Der vorherige Schlüssel funktioniert ab dem Moment, in dem dieser Aufruf erfolgreich ist, nicht mehr. Aktualisieren Sie daher jede Integration, die ihn verwendet hat.

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.

Antwort

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

Schlüssel widerrufen

Löscht den API-Schlüssel Ihres Kontos dauerhaft. Der Widerruf erfolgt sofort: Jede nachfolgende Anfrage, die den widerrufenen Schlüssel verwendet – einschließlich Integrationen wie Make, Zapier oder benutzerdefinierte Skripte – wird mit einem 401 abgelehnt. Um den API-Zugriff danach wiederherzustellen, generieren Sie einen neuen Schlüssel in Ihren Kontoeinstellungen, während Sie in der App angemeldet sind.

DELETE /api-keys/current

Dies kann nicht rückgängig gemacht werden. Im Gegensatz zur Rotation erhalten Sie beim Widerruf keinen Ersatzschlüssel. Widerrufen Sie den Zugriff nur, wenn Sie den API-Zugriff beenden möchten (zum Beispiel bei einem geleakten Schlüssel, den Sie nicht sofort ersetzen können).

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()

Antwort

{
  "success": true,
  "revoked": true,
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Wenn das Konto keinen Schlüssel zum Widerrufen hat, lautet die Antwort 404.

Bereichsbezogene Schlüssel

Ein bereichsbezogener Schlüssel ist ein zusätzlicher API-Schlüssel, den Sie für eine bestimmte Aufgabe erstellen und der nur die für diese Aufgabe erforderlichen Zugriffsrechte besitzt. Der klassische Anwendungsfall: Sie möchten ein Kunden-Dashboard, ein Reporting-Tool oder ein internes Skript mit Ihrem Konto verbinden, ohne einen Schlüssel weiterzugeben, der auch Nachrichten senden, Ihre KI-Agenten ändern oder Telefonnummern kaufen könnte.

Die Einschränkung ist fest mit dem Schlüssel verknüpft, sodass der Inhaber nur die Aktionen ausführen kann, die Sie bei der Erstellung zugelassen haben.

Was Sie einschränken können

Feld	Bedeutung
`read_only`	`true` (Standard) bedeutet, dass nur Leseanfragen erlaubt sind. Jede Erstellungs-, Aktualisierungs- oder Löschanfrage wird abgelehnt.
`tags`	Die Liste der API-Bereiche, die der Schlüssel verwenden darf, geschrieben mit denselben Bereichsnamen, die Sie in dieser Dokumentation und im API-Explorer sehen — `Analytics`, `Campaigns`, `Contacts`, `Messages`, `Appointments` usw. Eine leere Liste bedeutet alle Bereiche.
`sub_account_ids`	Auf welche verwalteten Konten der Schlüssel zugreifen darf. Leer bedeutet nur Ihr eigenes Konto; `["*"]` bedeutet jedes Konto, das Sie tatsächlich verwalten. Die Berechtigung wird bei jeder Anfrage erneut geprüft.
`rate_limit_per_min`	Anfragen pro Minute für diesen Schlüssel, die in einem eigenen Kontingent gezählt werden, damit sie das Limit Ihrer anderen Integrationen nicht ausschöpfen. Der Standardwert ist `60` und kann nicht höher als `300` eingestellt werden.

Sie können einem Schlüssel auch ein expires_at-Datum zuweisen (ISO 8601, muss in der Zukunft liegen). Nach diesem Zeitpunkt funktioniert der Schlüssel nicht mehr. Wenn Sie dieses Feld leer lassen, läuft der Schlüssel nie ab, bis Sie ihn widerrufen.

Ablehnungen sind sicherheitsorientiert. Wenn eine Anfrage außerhalb der erlaubten Bereiche des Schlüssels liegt, wird sie abgelehnt, anstatt sie zuzulassen: Ein Schreibzugriff mit einem Nur-Lese-Schlüssel gibt 403 mit error_code: "key_read_only" zurück, und alles außerhalb der erlaubten Bereiche des Schlüssels gibt 403 mit error_code: "key_scope_denied" zurück. Wenn ein bereichsbezogener Schlüssel einen unerwarteten 403-Fehler erhält, liegt der aufgerufene Endpunkt einfach nicht innerhalb seiner Bereiche — erweitern Sie die Berechtigungen des Schlüssels oder verwenden Sie Ihren Hauptschlüssel.

Nur der Kontoinhaber verwaltet Schlüssel. Diese vier Endpunkte erfordern Ihren Hauptschlüssel oder eine Inhaber-Sitzung in der App. Ein bereichsbezogener Schlüssel kann niemals Schlüssel auflisten, erstellen, bearbeiten oder widerrufen — auch nicht sich selbst —, sodass ein eingeschränkter Schlüssel niemals dazu verwendet werden kann, einen Schlüssel mit umfassenderen Rechten zu erstellen. Ein Versuch gibt 403 mit error_code: "key_scope_denied" zurück. Aus demselben Grund ist API Keys kein Bereich, den Sie gewähren können: Eine entsprechende Anfrage gibt 400 mit error_code: "invalid_scopes" zurück.

Bereichsbezogene Schlüssel auflisten

Gibt die bereichsbezogenen Schlüssel des Kontos zurück, beginnend mit den neuesten (bis zu 200), einschließlich widerrufener Schlüssel, damit Sie sehen können, was wann entzogen wurde. Es werden nur maskierte Vorschauen zurückgegeben — der Wert eines bereichsbezogenen Schlüssels wird nur einmal bei der Erstellung angezeigt und kann danach nie wieder abgerufen werden.

GET /api-keys

cURL

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

Antwort

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

Bereichsbezogenen Schlüssel erstellen

Erstellt einen neuen bereichsbezogenen Schlüssel und gibt dessen Wert einmalig zurück.

POST /api-keys

Der Schlüssel wird nur einmal angezeigt. Er ist in dieser Antwort enthalten und nirgendwo sonst – es gibt keine Möglichkeit, ihn nachträglich erneut abzurufen. Speichern Sie ihn in dem Moment, in dem Sie ihn erhalten. Wenn Sie ihn verlieren, widerrufen Sie ihn und erstellen Sie einen neuen.

Body-Felder — alle optional:

Feld	Typ	Hinweise
`label`	string	Ihr eigener Name für den Schlüssel, der in der Liste und in den Einstellungen angezeigt wird.
`scopes`	object	Die vier Felder in der obigen Tabelle. Lassen Sie das gesamte Objekt weg, um die sichere Standardeinstellung zu erhalten: schreibgeschützt, beschränkt auf `Analytics`, nur Ihr eigenes Konto, 60 Anfragen pro Minute.
`expires_at`	ISO 8601 Datum	Optionales Ablaufdatum, muss in der Zukunft liegen.

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.

Antwort — 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."
}

Ein paar Details, die Sie bei der Implementierung beachten sollten:

Das Weglassen von scopes ist nicht dasselbe wie das Senden einer leeren tags-Liste. Lassen Sie scopes vollständig weg, um die sichere Standardeinstellung zu erhalten (schreibgeschützt, nur Analytics). Senden Sie "tags": [] gezielt, kann der Schlüssel jeden Bereich nutzen – dies wird als bewusste Anforderung für einen uneingeschränkten Schlüssel gewertet.
read_only bleibt true, es sei denn, Sie senden explizit false. Ein Tippfehler oder ein fehlendes Flag kann niemals versehentlich einen Schlüssel erzeugen, der Schreibzugriff hat.

Einen bereichsbezogenen Schlüssel aktualisieren

Ändert die Bezeichnung, die Bereiche und/oder das Ablaufdatum eines Schlüssels. Senden Sie eine beliebige Kombination der drei; wenn Sie keines davon senden, wird 400 zurückgegeben.

PATCH /api-keys/{id}

Die {id} ist die id des Schlüssels aus der Liste (der key_...-Wert), niemals der Schlüssel selbst.

Bereiche werden ersetzt, nicht zusammengeführt. Was auch immer Sie senden, wird zum vollständigen Berechtigungssatz des Schlüssels. Das ist beabsichtigt: Das Einschränken eines Schlüssels kann niemals dazu führen, dass der alte, umfassendere Zugriff unbemerkt bestehen bleibt. Senden Sie immer das vollständige scopes-Objekt, das Sie wünschen, nicht nur das Feld, das Sie ändern möchten.

Der Wert des Schlüssels ändert sich nie. Es gibt kein direktes Rotieren für einen bereichsbezogenen Schlüssel – um einen zu erneuern, erstellen Sie einen neuen Schlüssel und widerrufen Sie den alten, damit sich der Zugriff einer Anmeldeinformation niemals unbemerkt ändern kann, während eine Integration sie noch verwendet.

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
    }
  }'

Antwort

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

Wenn es auf Ihrem Konto keinen Schlüssel mit dieser ID gibt, lautet die Antwort 404.

Einen bereichsbeschränkten Schlüssel widerrufen

Der Widerruf erfolgt sofort: Die nächste Anfrage, die diesen Schlüssel verwendet, wird mit einem 401 abgelehnt. Ihr Hauptschlüssel und alle anderen bereichsbeschränkten Schlüssel sind davon nicht betroffen.

DELETE /api-keys/{id}

Der Schlüssel verbleibt in Ihrer Liste mit der Markierung "revoked": true, sodass Sie nachvollziehen können, was existierte und worauf zugegriffen werden konnte. Das Widerrufen eines bereits widerrufenen Schlüssels ist erfolgreich und ändert nichts.

cURL

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

Antwort

{
  "success": true,
  "revoked": true,
  "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
  "message": "API key revoked. All requests using it will be rejected immediately."
}