Managing sitekeys¶

Besides the verification API, the Myra EU CAPTCHA operates a second interface: the API of the dashboard. Through it, you create sitekeys, read their settings, and change them. The dashboard itself uses this interface only.

The base URL is:

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

Warning

This interface serves the dashboard and is not part of version 1.1 of the public API. It has no assurance of stability and no description that can be called up in the browser. For the verification of tokens, use https://api.eu-captcha.eu/v1 only. See Verify a client token.

Log in¶

All calls require a token according to JSON Web Token. You receive it through the /login endpoint:

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": "••••••••"
      }'

The response contains the token:

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

If two-factor authentication is switched on for the account, the endpoint responds with the totp_required field and a preAuthToken value instead. The token follows only after the confirmation of the one-time password. See Set up two-factor authentication.

Pass the token in the header with every further call:

Authorization: Bearer <token>

Listing sitekeys¶

GET /captcha_sitekeys

The endpoint returns the sitekeys that belong to your account or for which you hold a permission. The following parameters are available:

Parameter	Description
`page`	Page of the result list.
`itemsPerPage`	Number of entries per page.
`light`	With `light=1`, the expensive metrics on the usage are omitted. The response then contains only the master data.

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

The response contains the entries in the member field and the total number in the totalItems field.

Reading a single sitekey¶

GET /captcha_sitekeys/{id}

{id} is the internal number of the sitekey, not its UUID.

Creating a sitekey¶

POST /captcha_sitekeys

The request uses the application/ld+json content type:

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": "Contact form"
      }'

The server creates the sitekey and the secret. The sitekey is a UUID, the secret a random value of 32 bytes in Base64. Both values are given in the response.

Changing a sitekey¶

PATCH /captcha_sitekeys/{id}

The request uses the application/merge-patch+json content type and contains only the fields that change:

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 }'

A sitekey is not removed but deactivated through the deleted field:

{ "deleted": true }

See Deleting a sitekey.

Fields¶

You set the following fields when creating and when changing:

Field	Create	Edit	Value range
`domain`	yes	no	Valid host name. The domain of an existing sitekey is not changed.
`label`	yes	yes	255 characters at most.
`train`	yes	yes	`true` or `false`. In training mode, the verification always responds successfully.
`maxParallel`	yes	yes	1 to 10.
`initialDelay`	yes	yes	3 to 30 seconds.
`initialDifficulty`	yes	yes	0 to 3.
`wizardCategory`	yes	no	Category from the installation wizard, 64 characters at most.
`wizardTechnology`	yes	no	Technology from the installation wizard, 64 characters at most.
`deleted`	no	yes	`true` deactivates the sitekey.

If a value is outside of the range, the server responds with an error and names the affected field. The section Configuring a sitekey describes the meaning of the settings.

Additional fields of the response¶

Besides the stored values, the response contains calculated fields:

Field	Meaning
`permissionLevel`	Your access to the sitekey: `owner`, `write`, `read`, or `none`.
`challengesServed`	Number of the challenges delivered in the most recent period.
`installationStatus`	`not_started`, `widget_installed`, or `fully_integrated`. The value only moves forward.
`recentActivity`	`active` or `inactive`.

The last three fields are omitted for a call with light=1.

Permissions¶

The access depends on the permission of the sitekey:

Permission	Read	Edit	Secret in the response
Owner	yes	yes	yes
`write`	yes	yes	yes
`read`	yes	no	no, the field is empty

You manage the permissions in the dashboard. See Grant access to a sitekey.