Sitekeys verwalten¶

Neben der Verifikations-API betreibt das Myra EU CAPTCHA eine zweite Schnittstelle: die API des Dashboards. Über sie legen Sie Sitekeys an, lesen deren Einstellungen und ändern sie. Das Dashboard selbst verwendet ausschließlich diese Schnittstelle.

Die Basis-URL lautet:

https://api-app.eu-captcha.eu/myra-auto-app-api

Warning

Diese Schnittstelle bedient das Dashboard und ist nicht Teil der Version 1.1 der öffentlichen API. Sie besitzt keine Zusicherung zur Stabilität und keine abrufbare Beschreibung im Browser. Für die Prüfung von Token verwenden Sie ausschließlich https://api.eu-captcha.eu/v1. Siehe Client-Token prüfen.

Anmelden¶

Alle Aufrufe benötigen einen Token nach JSON Web Token. Sie erhalten ihn über den Endpunkt /login:

curl -X POST https://api-app.eu-captcha.eu/myra-auto-app-api/login \
  -H "Content-Type: application/json" \
  -d '{
        "email": "max.mustermann@example.com",
        "password": "••••••••"
      }'

Die Antwort enthält den Token:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9••••"
}

Ist für das Konto die Zwei-Faktor-Authentifizierung eingeschaltet, antwortet der Endpunkt stattdessen mit dem Feld totp_required und einem Wert preAuthToken. Der Token folgt erst nach der Bestätigung des Einmalkennworts. Siehe Zwei-Faktor-Authentifizierung einrichten.

Übergeben Sie den Token bei jedem weiteren Aufruf in der Kopfzeile:

Authorization: Bearer <Token>

Sitekeys auflisten¶

GET /captcha_sitekeys

Der Endpunkt liefert die Sitekeys, die Ihrem Konto gehören oder für die Sie eine Freigabe besitzen. Die folgenden Parameter stehen zur Verfügung:

Parameter	Beschreibung
`page`	Seite der Ergebnisliste.
`itemsPerPage`	Anzahl der Einträge je Seite.
`light`	Mit `light=1` entfallen die aufwendigen Kennzahlen zur Nutzung. Die Antwort enthält dann nur die Stammdaten.

curl "https://api-app.eu-captcha.eu/myra-auto-app-api/captcha_sitekeys?page=1&itemsPerPage=10" \
  -H "Authorization: Bearer <Token>"

Die Antwort enthält die Einträge im Feld member und die Gesamtzahl im Feld totalItems.

Einzelnen Sitekey lesen¶

GET /captcha_sitekeys/{id}

{id} ist die interne Nummer des Sitekeys, nicht dessen UUID.

Sitekey anlegen¶

POST /captcha_sitekeys

Die Anfrage verwendet den Inhaltstyp application/ld+json:

curl -X POST https://api-app.eu-captcha.eu/myra-auto-app-api/captcha_sitekeys \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/ld+json" \
  -d '{
        "domain": "example.com",
        "label": "Kontaktformular"
      }'

Den Sitekey und das Secret erzeugt der Server. Der Sitekey ist eine UUID, das Secret ein Zufallswert mit 32 Byte in Base64. Beide Werte stehen in der Antwort.

Sitekey ändern¶

PATCH /captcha_sitekeys/{id}

Die Anfrage verwendet den Inhaltstyp application/merge-patch+json und enthält nur die Felder, die sich ändern:

curl -X PATCH https://api-app.eu-captcha.eu/myra-auto-app-api/captcha_sitekeys/42 \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{ "initialDifficulty": 2 }'

Ein Sitekey wird nicht entfernt, sondern über das Feld deleted stillgelegt:

{ "deleted": true }

Siehe Sitekey löschen.

Felder¶

Die folgenden Felder setzen Sie beim Anlegen und beim Ändern:

Feld	Anlegen	Ändern	Wertebereich
`domain`	ja	nein	Gültiger Hostname. Die Domain eines bestehenden Sitekeys ändern Sie nicht.
`label`	ja	ja	Höchstens 255 Zeichen.
`train`	ja	ja	`true` oder `false`. Im Trainingsmodus antwortet die Verifikation stets erfolgreich.
`maxParallel`	ja	ja	1 bis 10.
`initialDelay`	ja	ja	3 bis 30 Sekunden.
`initialDifficulty`	ja	ja	0 bis 3.
`wizardCategory`	ja	nein	Kategorie aus dem Installationsassistenten, höchstens 64 Zeichen.
`wizardTechnology`	ja	nein	Technologie aus dem Installationsassistenten, höchstens 64 Zeichen.
`deleted`	nein	ja	`true` legt den Sitekey still.

Liegt ein Wert außerhalb des Bereichs, antwortet der Server mit einem Fehler und nennt das betroffene Feld. Die Bedeutung der Einstellungen beschreibt der Abschnitt Sitekey konfigurieren.

Zusätzliche Felder der Antwort¶

Neben den gespeicherten Werten enthält die Antwort berechnete Felder:

Feld	Bedeutung
`permissionLevel`	Ihr Zugriff auf den Sitekey: `owner`, `write`, `read` oder `none`.
`challengesServed`	Anzahl der ausgelieferten Challenges im jüngsten Zeitraum.
`installationStatus`	`not_started`, `widget_installed` oder `fully_integrated`. Der Wert schreitet nur vorwärts.
`recentActivity`	`active` oder `inactive`.

Die drei letzten Felder entfallen bei einem Aufruf mit light=1.

Berechtigungen¶

Der Zugriff richtet sich nach der Freigabe des Sitekeys:

Freigabe	Lesen	Ändern	Secret in der Antwort
Eigentümer	ja	ja	ja
`write`	ja	ja	ja
`read`	ja	nein	nein, das Feld ist leer

Freigaben verwalten Sie im Dashboard. Siehe Zugriff auf einen Sitekey gewähren.