Example use cases and implementation
Using BotGuard's GateKeeper APIs, you can implement your own desired seqeunce of dependent requests, as demonstrated in the following implementation examples.
Simple integrations
In this example, the partner does not intend to manage bot protection rules via the API. The API will only be used to create users/subaccounts and add websites. The partner then intends for users to manage bot protection rules via the BotGuard dashboard, using Single-Sign-On (SSO) or by imbedding BotGuard's dashboard as frames into the their own control panel.
Protect your API Key
The namespace structure is very simple in this example, with no devices or servers present.
Using Content-Type: application/x-www-form-urlencoded header is sufficient for all calls with simple integration. The call sequence to add a user with a website and to implement the BotGuard dashboard UI embedding is as follows:
-
Create a user/subaccount:
Create a user/subaccount: curl --location --request POST 'https://<GATEKEEPER-IP:PORT>/v1.0/user' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \ --data-urlencode 'id=user@domain.com'Returns:
-
Create a website under the user's account:
curl --location --request POST 'https://<GATEKEEPER-IP:PORT>/v1.0/website' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \ --data-urlencode 'user_id=user@domain.com' \ --data-urlencode 'domain=example.com' \ --data-urlencode 'subdomain=www' \ --data-urlencode 'ip=123.123.123.123' \ --data-urlencode 'tag=DC1' \ --data-urlencode 'callbackUrl=https://customer-portal.local/webhooks/website'A partner may also update website configuration, like in the example below, where a webmail subdomain is added to the existing website:
-
Embed the BotGuard dashboard UI
First, retrieve the user's API KEY:
This returns:curl --location 'https://<GATEKEEPER-IP:PORT>/v1.0/user/user@domain.com' \ --header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'Then draw frames in the partner's Control Panel with the user's API KEY. For example, for the Rules Editor:
Integrations without embedding the BotGuard UI
If a partner chooses to not embed BotGuard UI into their Control Panel, it is necessary to automate the management of protection rules via the API. To implement rules management via API, partners must use the Content-Type: application/json header and JSON-formatted payloads with the /website collection.
-
The example below creates a website under the existing user with ID user@domain.com, with assigned custom SSL certificate, and with configured protection rules:
curl --location --request POST 'https://<GATEKEEPER-IP:PORT>/v1.0/website' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \ --data-raw '{ "domain": "example.com", "subdomain": [], "user_id": "user@domain.com", "ip": [ "123.123.123.123" ], "tag": [ "DC1" ], "status": "online", "certificate":{ "public":"<Public-Certificate-Bundle>", "private":"<Private-Key>" }, "settings": { "rulesets": { "bitrix": false, "cpanel": false, "dokuwiki": false, "drupal": false, "joomla": false, "nextcloud": false, "prestashop": false, "wordpress": true, "xenforo": false }, "rules": { "content_scrapers": "deny", "emulated_humans": "deny", "humans": "grant", "search_engines": "grant", "security_issues": "deny", "services_and_payments": "grant", "social_networks": "grant", "suspicious_behaviour": "captcha" }, "loadbalancer": { "upstreams_use_https": true, "enable_http3": true, "force_https": true, "cache_static_files": true, "cache_dynamic_pages": false, "ddos_protection": false, "ddos_protection_advanced": false, "botguard_protection": true, "certs_issuer": "custom", "force_subdomains_redirect": true } } }' -
Once the website is created, a partner may update the configuration. The example below adds a www subdomain to an existing website and switches the bot protection policy for Suspicious Behaviour to "deny":
curl --location --request PUT 'https://<GATEKEEPER-IP:PORT>/v1.0/website/example.com' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \ --data '{ "domain": "example.com", "subdomain": ["www"], "settings":{ "rules":{ "suspicious_behaviour": "deny" } } }'
Asynchronous API call execution
Websites are not usually ready immediately after initial creation or after editing their settings. While DNS records are being changed and propagated, or GateKeeper is issuing an SSL certificate; the status of the website may change in BotGuard. To facilitate synchronization of the website status with a partner's control panel, a partner may opt to use Asynchronous call execution by specifying a callback URL in any of the API calls to create and change websites. Asynchronous call execution can be used with either application/json or application/x-www-form-urlencoded headers by specifying the callbackUrl parameter.
The example below changes the certificate to a certificate issued by Lets Encrypt. GateKeeper issues the requested certificate with the Lets Encrypt CA using ACME protocol, which normally takes several minutes. After the certificate is issued, GateKeeper sends a web hook to the provided callbackUrl:
curl --location --request PUT 'https://<GATEKEEPER-IP:PORT>/v1.0/website/example.com' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--data '{
"domain": "example.com",
"subdomain": ["www"],
"callbackUrl":"https://customer-portal.local/webhooks/website",
"settings":{
"loadbalancer":{
"certs_issuer": "letsencrypt"
}
}
}'