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

Achtung

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. Gelöschte Sitekeys fehlen in der Liste. Die folgenden Parameter stehen zur Verfügung:

Parameter	Beschreibung
`page`	Seite der Ergebnisliste.
`itemsPerPage`	Anzahl der Einträge je Seite.
`search`	Schränkt die Liste ein. Der Wert wird ohne Rücksicht auf Groß- und Kleinschreibung als Teilzeichenkette in den Feldern `domain` und `label` gesucht.
`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`.
`trialState`	`active` oder `trial_expired`. Der Wert ist nur lesbar und folgt der Testphase des Eigentümers. Siehe Testphase.
`challengesServed`	Anzahl der ausgelieferten Challenges der letzten sieben Tage.
`installationStatus`	`not_started`, `widget_installed` oder `fully_integrated`. Der Wert schreitet nur vorwärts.
`recentActivity`	`active`, `inactive` oder `null`. Der Wert `active` steht für eine serverseitige Prüfung innerhalb der letzten 24 Stunden. Der Wert ist `null`, solange `installationStatus` nicht `fully_integrated` ist.

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.