OAuth für Apps

Ihre App verbindet sich mit einem Klick mit dem Cord-Konto eines Unternehmens, ohne dass jemand einen Schlüssel kopiert.

Wann Sie es verwenden

Wenn Sie eine App bauen, die viele Unternehmen mit ihrem Cord-Konto verbinden sollen – einen Connector, ein Add-on, eine Automatisierungsplattform –, verwenden Sie OAuth 2.0, statt nach einem API-Schlüssel zu fragen. Die Person autorisiert auf einer Seite von Cord, wählt den Arbeitsbereich und kann den Zugriff jederzeit widerrufen. Es ist derselbe Mechanismus, den die Apps von Cord in Zapier und Make sowie das Add-on von Cord für Gmail verwenden.

Für eine Integration Ihres eigenen Unternehmens ist ein API-Schlüssel einfacher.

Ihre App registrieren

Die Registrierung von OAuth-Clients ist noch nicht im Self-Service möglich. Schreiben Sie an contacto@cordhq.app mit dem Namen Ihrer App, ihrer Domain und den exakten Rücksprungadressen (redirect_uri). Sie erhalten eine client_id und ein client_secret. Bewahren Sie das Secret auf Ihrem Server auf: Cord speichert nur seinen Fingerabdruck und kann es nicht erneut anzeigen.

Rücksprungadressen müssen https sein (oder http://localhost für die Entwicklung) und werden exakt verglichen, ohne Platzhalter.

1. Autorisierung anfordern

Leiten Sie die Person weiter zu:

https://cordhq.app/oauth/authorize
  ?response_type=code
  &client_id=cord_oc_...
  &redirect_uri=https://yourapp.com/cord/callback
  &scope=write
  &state=RANDOM_VALUE
  &code_challenge=...            (optional, PKCE)
  &code_challenge_method=S256    (optional, PKCE)

Parameter	Detail
`scope`	`read` für reinen Lesezugriff; `write` für Lese- und Schreibzugriff (enthält `read`). Ohne `scope` fordert Cord `read` an. Sie können Werte mit Leerzeichen, Komma oder `+` trennen; jeder andere Wert führt zu `invalid_scope`.
`state`	Ein Zufallswert, den Ihre App beim Rücksprung prüft. Er verhindert, dass ein Dritter Ihnen eine Autorisierung unterschiebt.
`code_challenge`	PKCE: `BASE64URL(SHA256(code_verifier))`, 43 Zeichen ohne Padding. Immer empfohlen; nur `code_challenge_method=S256` wird akzeptiert.

Ist die Person nicht angemeldet, bittet Cord sie, sich anzumelden, und kehrt dann zur selben Seite zurück. Nur wer in einem Arbeitsbereich die Berechtigung Einstellungen hat, kann dort Apps autorisieren. Die Seite zeigt, was Ihre App tun kann und was nicht.

Nach der Autorisierung kehrt Cord mit ?code=...&state=... zu Ihrer redirect_uri zurück. Bricht die Person ab, kommt der Rücksprung mit ?error=access_denied&state=....

2. Den Code austauschen

Der Code gilt 5 Minuten und funktioniert nur einmal. Tauschen Sie ihn von Ihrem Server aus ein:

curl -X POST "https://cordhq.app/api/oauth/token" \
     -d grant_type=authorization_code \
     -d code=cord_ac_... \
     -d redirect_uri=https://yourapp.com/cord/callback \
     -d client_id=cord_oc_... \
     -d client_secret=cord_cs_... \
     -d code_verifier=...

Sie können die Client-Zugangsdaten auch per HTTP-Basic-Authentifizierung senden.

{ "access_token": "cord_at_...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "cord_rt_...", "scope": "write" }

3. Die API aufrufen

Das access_token funktioniert wie ein Schlüssel in der gesamten API v1 und im MCP-Server:

curl "https://cordhq.app/api/v1/me" -H "Authorization: Bearer cord_at_..."

4. Den Zugriff erneuern

Das Access Token gilt 1 Stunde. Erneuern Sie es mit dem Refresh Token, das 180 Tage gilt:

curl -X POST "https://cordhq.app/api/oauth/token" \
     -d grant_type=refresh_token \
     -d refresh_token=cord_rt_... \
     -d client_id=cord_oc_... \
     -d client_secret=cord_cs_...

Jede Erneuerung liefert ein neues Refresh Token, und das vorherige wird ungültig. Speichern Sie immer das neue. Wird ein bereits verwendetes Refresh Token nach mehr als 30 Sekunden erneut vorgelegt, behandelt Cord das als möglichen Diebstahl und widerruft die gesamte Verbindung; die Person muss dann erneut autorisieren.

5. Widerrufen

curl -X POST "https://cordhq.app/api/oauth/revoke" \
     -d token=cord_rt_... -d client_id=cord_oc_... -d client_secret=cord_cs_...

Die Antwort ist 200, auch wenn das Token nicht existiert, damit nicht erkennbar ist, welche Tokens gültig sind. Die Person kann Ihre App auch im Tab Schlüssel der Cord Workbench widerrufen, wo sie als Autorisierte Verbindung erscheint.

PKCE

PKCE verhindert, dass ein abgefangener Code eingetauscht werden kann. Erzeugen Sie einen zufälligen code_verifier mit 43 bis 128 Zeichen (A-Z, a-z, 0-9, -, ., _, ~), speichern Sie ihn in der Sitzung Ihres Servers und senden Sie beim Autorisieren seinen Hash:

import { createHash, randomBytes } from 'node:crypto';

const codeVerifier = randomBytes(48).toString('base64url'); // 64 Zeichen
const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url'); // 43 Zeichen
// In /oauth/authorize: code_challenge=<codeChallenge>&code_challenge_method=S256
// In /api/oauth/token: code_verifier=<codeVerifier>

Haben Sie beim Autorisieren code_challenge gesendet, verlangt der Austausch den passenden code_verifier. Haben Sie es nicht gesendet, darf der Austausch keinen code_verifier enthalten: Ein unerwarteter führt ebenfalls zu invalid_grant.

Fehler bei der Autorisierung

Bei /oauth/authorize gibt es zwei Arten von Fehlern, und sie verhalten sich bewusst unterschiedlich.

Cord kehrt nicht zu Ihrer App zurück, wenn es der Rücksprungadresse nicht vertrauen kann. Die Person sieht eine Fehlerseite von Cord, und es wird nichts weitergeleitet:

Situation	Was passiert
Eine `client_id`, die nicht existiert	Fehlerseite von Cord (`unknown_client`).
Eine `redirect_uri`, die nicht exakt mit einer registrierten übereinstimmt	Fehlerseite von Cord. Prüfen Sie Groß- und Kleinschreibung, abschließenden Schrägstrich und Port.

Cord kehrt zu Ihrer redirect_uri zurück, mit error und Ihrem state, wenn Client und Adresse gültig sind, die Anfrage aber nicht:

`error`	Wann
`unsupported_response_type`	`response_type` ist nicht `code`.
`invalid_scope`	`scope` enthält einen anderen Wert als `read` oder `write`.
`invalid_request`	Ein fehlerhaftes `code_challenge` oder eine andere `code_challenge_method` als `S256`.
`access_denied`	Die Person hat abgebrochen oder einen Arbeitsbereich gewählt, in dem sie keine Apps autorisieren darf.

https://yourapp.com/cord/callback?error=invalid_scope&state=RANDOM_VALUE

Diese Weiterleitungen enthalten keine error_description. Prüfen Sie immer, ob state der Wert ist, den Sie gesendet haben, bevor Sie den Fehler anzeigen.

Fehler beim Austausch und bei der Erneuerung

POST /api/oauth/token akzeptiert den Body als application/x-www-form-urlencoded oder als JSON und antwortet immer mit JSON, das error und error_description enthält:

{ "error": "invalid_grant", "error_description": "El código o el token no es válido, ya se usó o venció." }

Status	`error`	`error_description`	Wann
`401`	`invalid_client`	Las credenciales de la aplicación no son válidas.	Falsche `client_id` oder falsches `client_secret`, per Basic oder im Body.
`400`	`invalid_request`	El cuerpo de la petición no se pudo leer.	Der Body ist weder ein gültiges Formular noch gültiges JSON.
`400`	`invalid_request`	Faltan code o redirect_uri.	Austausch ohne `code` oder ohne `redirect_uri`.
`400`	`invalid_request`	Falta refresh_token.	Erneuerung ohne `refresh_token`.
`400`	`invalid_request`	Este espacio ya tiene demasiadas conexiones de esta aplicación…	Der Arbeitsbereich hat bereits 25 aktive Verbindungen Ihrer App. Die Person muss nicht genutzte widerrufen.
`400`	`unsupported_grant_type`	Solo se admite authorization_code y refresh_token.	Jeder andere `grant_type`.
`400`	`invalid_grant`	El código o el token no es válido, ya se usó o venció.	Abgelaufener oder bereits verwendeter Code, eine andere `redirect_uri` als bei der Autorisierung, ein `code_verifier`, der nicht passt, oder ein Refresh Token, das abgelaufen, bereits verwendet oder von einem anderen Client ist.
`429`	—	—	Mehr als 300 Anfragen pro Minute von derselben IP-Adresse. Beachten Sie `Retry-After`.

error_description ist auf Spanisch und kann sich ändern: Entscheiden Sie anhand von error.

POST /api/oauth/revoke antwortet mit 401 und error: "invalid_client", wenn die Client-Zugangsdaten ungültig sind, und in allen anderen Fällen mit 200.

Kontingent

Aufrufe mit einem OAuth-Token zählen gegen das API-Kontingent im Tarif des Unternehmens, genau wie ein Schlüssel. Die einzige Ausnahme ist das Add-on von Cord für Gmail, eine Oberfläche von Cord selbst: Seine Aufrufe verbrauchen nicht das monatliche Kontingent, zählen aber gegen die Minutenlimits.