Authentifizierung

Alle Anfragen an die NueForm-API erfordern eine Authentifizierung per API-Schlüssel. Diese Anleitung zeigt dir, wie du Schlüssel erstellst, sie in Anfragen verwendest und sicher aufbewahrst.

API-Schlüssel erstellen

So erstellst du einen API-Schlüssel:

1. Melde dich in deinem NueForm-Konto an.
2. Öffne dein Profil und wechsle zum Tab Developer.
3. Klicke auf Create API Key.
4. Gib deinem Schlüssel einen aussagekräftigen Namen (z. B. „Production Backend" oder „CI Pipeline").
5. Kopiere den Schlüssel sofort --- er wird nur ein einziges Mal angezeigt.

Format der API-Schlüssel

NueForm-API-Schlüssel folgen einem einheitlichen Format:

nf_<64 hex characters>

Jeder Schlüssel beginnt mit dem Präfix nf_, gefolgt von 64 Hexadezimalzeichen (32 zufällige Bytes). Zum Beispiel:

nf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Im Dashboard werden Schlüssel anhand ihres Präfixes identifiziert (die ersten 11 Zeichen, z. B. nf_a1b2c3d4), sodass du sie auseinanderhalten kannst, ohne den vollständigen Wert offenzulegen.

Deinen API-Schlüssel verwenden

Übergib deinen API-Schlüssel im Authorization-Header jeder Anfrage mit dem Bearer-Schema:

Authorization: Bearer nf_your_api_key_here

cURL

curl -X GET https://app.nueform.io/api/v1/forms \
  -H "Authorization: Bearer nf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json"

JavaScript (fetch)

const NUEFORM_API_KEY = process.env.NUEFORM_API_KEY;

const response = await fetch("https://app.nueform.io/api/v1/forms", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${NUEFORM_API_KEY}`,
    "Content-Type": "application/json",
  },
});

const { data } = await response.json();
console.log(data);

Python (requests)

import os
import requests

api_key = os.environ["NUEFORM_API_KEY"]

response = requests.get(
    "https://app.nueform.io/api/v1/forms",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
)

data = response.json()["data"]
print(data)

Authentifizierungsfehler

Wenn die Authentifizierung fehlschlägt, gibt die API eine 401 Unauthorized-Antwort mit einer aussagekräftigen Meldung zurück:

Beispiel für eine Fehlerantwort:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key.",
    "status": 401
  }
}

Schlüsselverwaltung

Limits

Jedes NueForm-Konto kann gleichzeitig bis zu 10 aktive API-Schlüssel haben. Wenn du einen neuen Schlüssel erstellen möchtest und das Limit erreicht hast, widerrufe zuerst einen bestehenden Schlüssel.

Schlüssel widerrufen

Du kannst einen API-Schlüssel jederzeit im Tab Developer in deinem Profil widerrufen. Der Widerruf wirkt sofort --- jede Anfrage mit einem widerrufenen Schlüssel erhält eine 401 Unauthorized-Antwort.

So widerrufst du einen Schlüssel:

1. Gehe zu Profil > Developer.
2. Suche den Schlüssel, den du widerrufen möchtest (erkennbar an Name und Präfix).
3. Klicke auf Revoke.
4. Bestätige die Aktion.

Nachverfolgung der letzten Verwendung

NueForm protokolliert, wann jeder API-Schlüssel zuletzt verwendet wurde. Im Tab Developer siehst du, welche Schlüssel aktiv genutzt werden und welche du vermutlich gefahrlos widerrufen kannst.

Tarifvoraussetzungen

API-Zugriff ist eine kostenpflichtige Funktion, die einen bezahlten Tarif voraussetzt:

Wenn du einen API-Schlüssel mit einem Konto verwendest, dessen Tarif keinen API-Zugriff enthält, erhältst du eine 403 Forbidden-Antwort:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API access is not available on your current plan.",
    "status": 403
  }
}

Voice-API-Schlüssel

Ein Voice-Schlüssel erzeugt Sprache und fragt deine Credits ab: Er kann die Voice-API (/api/v1/voice und alles darunter) und GET /api/v1/credits aufrufen, sonst nichts. Er kann deine Formulare und Antworten nicht sehen. Schlüssel mit Vollzugriff können die Voice-API ebenfalls aufrufen.

• Wer einen erstellen kann: jeder Tarif, sobald das Konto einen ersten Credit-Kauf getätigt hat (ein beliebiges Paket, ab 1 $) oder einen bezahlten Tarif nutzt und seine E-Mail-Adresse bestätigt ist. Klicke unter Profil > Developer auf API-Key erstellen und wähle Voice.
• Was er ausgibt: Credits aus deinem Guthaben, 0,4 pro gesprochenem Zeichen in jeder Sprache. Schätzungen sind kostenlos.
• Monatliches Credit-Limit (optional): Lege es beim Erstellen oder Bearbeiten des Schlüssels fest. Sobald der Schlüssel in einem Kalendermonat (UTC) so viel ausgegeben hat, erhalten seine Anfragen, die Sprache erzeugen oder etwas löschen, bis zum 1. 403 mit reason: "key_limit_reached"; abrufen und herunterladen, was er erzeugt hat, kann er weiterhin, und deine anderen Schlüssel funktionieren weiter. Jeder Schlüssel zeigt, was er in diesem Monat ausgegeben hat.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This API key can only use the Voice API. Use a full-access key (Pro plan) for this endpoint.",
    "status": 403,
    "reason": "scope_not_allowed"
  }
}

Best Practices für die Sicherheit

Halte dich an diese Richtlinien, um deine API-Schlüssel zu schützen:

Schlüssel niemals in die Versionsverwaltung committen

Füge deine Schlüsseldateien zu .gitignore hinzu und verwende stattdessen Umgebungsvariablen. Wenn ein Schlüssel versehentlich committet wurde, widerrufe ihn sofort und erstelle einen neuen.

# .env (add .env to your .gitignore)
NUEFORM_API_KEY=nf_your_api_key_here

Umgebungsvariablen verwenden

Speichere API-Schlüssel in jeder Umgebung in Umgebungsvariablen --- in der lokalen Entwicklung, im Staging und in der Produktion. Schreibe Schlüssel niemals fest in den Quellcode deiner Anwendung.

// Good
const apiKey = process.env.NUEFORM_API_KEY;

// Bad --- never do this
const apiKey = "nf_a1b2c3d4...";

Separate Schlüssel pro Umgebung verwenden

Erstelle eigene API-Schlüssel für Entwicklung, Staging und Produktion. Das begrenzt den Schaden, falls ein Schlüssel kompromittiert wird, und macht es einfach, den Zugriff einer einzelnen Umgebung zu widerrufen.

Schlüssel regelmäßig rotieren

Erstelle in regelmäßigen Abständen neue Schlüssel und lasse alte auslaufen. NueForm erlaubt bis zu 10 aktive Schlüssel — du kannst also einen neuen Schlüssel erstellen, deine Dienste aktualisieren, alles prüfen und anschließend den alten Schlüssel widerrufen.

Nur serverseitig verwenden

API-Schlüssel sollten ausschließlich in serverseitigem Code verwendet werden. Verwende deinen API-Schlüssel niemals in clientseitigem JavaScript, in Mobile-Apps oder in Code, der im Browser der Nutzer läuft.