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

Attention

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. Deleted sitekeys are not in the list. The following parameters are available:

Parameter	Description
`page`	Page of the result list.
`itemsPerPage`	Number of entries per page.
`search`	Limits the list. The service looks for the value as a substring in the `domain` and `label` fields and ignores the case.
`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`.
`trialState`	`active` or `trial_expired`. The value is read-only and follows the trial period of the owner. See Trial period.
`challengesServed`	Number of the challenges delivered in the last seven days.
`installationStatus`	`not_started`, `widget_installed`, or `fully_integrated`. The value only moves forward.
`recentActivity`	`active`, `inactive`, or `null`. The `active` value stands for a server-side verification within the last 24 hours. The value is `null` while `installationStatus` is not `fully_integrated`.

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.