Authentifizierung

So strukturieren Sie Ihre authentifizierten Anfragen an die Server von Cord.

Bearer Tokens

Die Cord-API verwendet Bearer Tokens, um eingehende Anfragen zu authentifizieren. Senden Sie den API-Schlüssel, den Sie im Dashboard erstellt haben, als HTTP-Header Authorization.

Alle Anfragen müssen über HTTPS erfolgen. Anfragen ohne Authentifizierung oder über unverschlüsseltes HTTP schlagen fehl.

Beispielanfrage:

curl -X GET "https://cordhq.app/api/v1/cotizaciones" \
     -H "Authorization: Bearer sk_live_tU..."

Geheime und öffentliche Schlüssel

Cord kennt drei Arten von Schlüsseln:

Geheim (sk_): nur auf Ihren Servern. Nur lesend oder lesend und schreibend für die gesamte API.
Eingeschränkt (rk_): nur auf Ihren Servern, mit einer Berechtigung pro Ressource (none, read oder write). Verwenden Sie sie, um einer Drittanbieter-Integration genau das zu geben, was sie braucht. Siehe eingeschränkte Schlüssel.
Öffentlich (pk_): für den Browser, mit einer festen Liste von Routen.

Automatische Datenmaskierung

Öffentliche Schlüssel unterliegen automatischen Sicherheitseinschränkungen der API. Wenn Sie zum Beispiel die Produkte-API mit einem öffentlichen Schlüssel abfragen, lässt der Server von Cord das Feld costo (Marge) automatisch weg, damit die Besucher Ihrer Website Ihre Gewinnmargen nicht herausfinden können.

Außerdem kann ein öffentlicher Schlüssel nur auf vier Routen verwendet werden: GET /api/v1/productos, POST /api/v1/cotizaciones, GET /api/v1/elements/config und POST /api/v1/elements/ai-draft. Jede andere Route antwortet mit 403 insufficient_scope. Die Anfrage muss außerdem einen Header Origin oder Referer senden, der zu den erlaubten Domains Ihrer Organisation passt; diese konfigurieren Sie unter Einstellungen › Einbettbarer Angebotsrechner. Ein pk_live_-Schlüssel ohne konfigurierte Domains antwortet mit 403 origin_allowlist_required; ein pk_test_-Schlüssel wird von jedem Ursprung akzeptiert.

Achtung: Legen Sie Ihre geheimen Schlüssel niemals offen. Wird Ihr geheimer Schlüssel kompromittiert, müssen Sie ihn sofort im Tab Schlüssel der Cord Workbench widerrufen.

Eingeschränkte Schlüssel

Ein rk_-Schlüssel trägt eine Stufe pro Ressource. Cord leitet die Ressource aus der Route ab, sodass eine neue API-Route für bestehende eingeschränkte Schlüssel zunächst gesperrt ist, bis Sie die Berechtigung erteilen.

Ressource	Routen
`cotizaciones`	`/api/v1/cotizaciones/*`
`clientes`	`/api/v1/clientes/*`
`productos`	`/api/v1/productos/*`
`facturas`	`/api/v1/facturas/*`
`cobranza`	`/api/v1/cobranza`
`tareas`	`/api/v1/tareas`
`eventos`	`/api/v1/events`
`webhooks`	`/api/v1/webhooks/*`
`elements`	`/api/v1/elements/*`
`test_helpers`	`/api/v1/test_helpers/*`
`setup`	`/api/v1/setup/*`

read erlaubt GET; write erlaubt zusätzlich Anlegen, Bearbeiten und Aktionen. GET /api/v1/me antwortet auf jeden geheimen oder eingeschränkten Schlüssel. Auf dem MCP-Server wendet ein eingeschränkter Schlüssel dieselbe Stufe pro Ressource auf jedes Tool an (siehe Berechtigungen pro Tool). Ohne Berechtigung lautet die Antwort 403 insufficient_permissions und nennt die Ressource.

Erlaubte IPs

Für einen sk_- oder rk_-Schlüssel können Sie bis zu 20 IPs oder CIDR-Bereiche (IPv4 oder IPv6) festlegen. Cord vergleicht die Quell-IP, die sein Auslieferungsnetz erfasst, nicht einen Header, den der Client selbst schreiben kann; X-Forwarded-For hebelt die Liste also nicht aus. Eine Anfrage von einer anderen IP antwortet mit 403 ip_not_allowed und wird im Audit-Log Ihrer Organisation festgehalten, einmal pro Stunde und IP.

Öffentliche Schlüssel werden unter Einstellungen › Einbettbarer Angebotsrechner nach Domain begrenzt, nicht nach IP.

Ablauf und Rotation

Beim Erstellen eines Schlüssels können Sie festlegen, dass er nach 7, 30, 90 oder 365 Tagen abläuft; danach antwortet er mit 401 key_expired. Rotieren erstellt einen neuen Schlüssel mit denselben Berechtigungen, IPs und derselben API-Version und lässt den alten so lange aktiv, wie Sie wählen (sofort, 1 Stunde, 24 Stunden oder 7 Tage), während Sie Ihre Systeme aktualisieren. Der Schlüssel in der Übergangsfrist zählt nicht mehr gegen das Limit Ihres Tarifs. Das Erstellen, Bearbeiten, Rotieren und Widerrufen von Schlüsseln wird im Audit-Log mit der handelnden Person und der IP festgehalten.

Enthaltene Schlüssel pro Tarif

Jeder Tarif enthält eine Höchstzahl aktiver Schlüssel: 2 im kostenlosen Tarif, 5 in Starter, 20 in Professional, 50 in Scale und 200 in Developer. Es zählen geheime, eingeschränkte und öffentliche Schlüssel, die weder widerrufen noch abgelaufen sind noch sich in der Übergangsfrist einer Rotation befinden; per OAuth autorisierte Verbindungen (Zapier, Make) zählen nicht. Ist die Grenze erreicht, lässt die Workbench Sie keinen weiteren Schlüssel erstellen, bis Sie einen widerrufen.

Hat Ihre Organisation mehr aktive Schlüssel, als ihr Tarif enthält (zum Beispiel nach einem Downgrade), funktionieren die ältesten weiter, und die Schlüssel über dem Kontingent antworten mit 402 subscription_key_limit, bis Sie Schlüssel widerrufen oder upgraden.

Schnelle Identitätsprüfung

Wenn Sie prüfen möchten, ob Ihr API-Schlüssel korrekt funktioniert und zu welchem Konto er gehört, verwenden Sie den Endpoint me:

curl -X GET "https://cordhq.app/api/v1/me" \
     -H "Authorization: Bearer sk_live_tU..."