Get Started with WatchGuard APIs

WatchGuard provides public RESTful APIs you can use for integration with WatchGuard products and services.

WatchGuard public APIs use token-based authentication. In each request to a WatchGuard API you specify an API key, which identifies your account, and an access token, which authorizes API access for a period of time.

To get started with WatchGuard APIs:

  1. Enable API Access.
  2. Get an Access Token.
  3. Make an API Request.

To discuss WatchGuard public APIs with other developers or to ask questions, visit the WatchGuard Community.

Enable API Access

When you enable API access, you establish credentials for read-write and read-only API requests and generate an API Key. WatchGuard Cloud supports API access for both Service Provider and Subscriber accounts.

To enable API access, you must have the Owner or Administrator operator role in WatchGuard Cloud.

To enable API access:

  1. Log in to your WatchGuard Cloud account.
  2. If you are a Service Provider, go to Subscriber view for your own account or a managed account.
  3. Select Administration > Managed Access.

  4. Click Enable API Access.

  5. Specify the readwrite and readonly passwords to use as your API access credentials. Passwords must be at least 12 characters long and include a lowercase letter, uppercase letter, number, and symbol. The password must not include <, >, emojis, or spaces.

    The readwrite password and the readonly password must be different.

  6. Select the I agree to the terms and conditions in the WatchGuard APIs License Agreement check box.
  7. Click Save.

    Screen shot of RESTful API Access enabled

After you enable API access, you see this information: 

  • Access ID (Read-write) — Specify this ID and the read-write password as the credentials in an API request to generate an API access token that allows read-write access.
  • Access ID (Read-only) — Specify this ID and the read-only password as the credentials in an API request to generate an API access token that allows read-only access.
  • Authentication API URL — To generate an access token, send a request to the URL of this WatchGuard Authentication API endpoint.
  • API URL (base) — The base URL for WatchGuard public API requests.
  • API Key — Specify this as the value of the WatchGuard-API-Key header parameter in all requests to WatchGuard public APIs.

The Authentication API URL and API URL (base) depend on your WatchGuard Cloud account data storage region and might be different from what you see in the example requests in WatchGuard API documentation.

Get an Access Token

To get an access token from the WatchGuard Authentication API, make a request to the /oauth/token endpoint.

In the Authorization header parameter, include the text "Basic" followed by a space and the credentials read-write access ID:read-write password encoded into base64:

curl -X POST https://api.usa.cloud.watchguard.com/oauth/token 
	-H 'accept: application/json' 
	-H 'Authorization: Basic dXNlcm5hbWU6N3loVHI1RHNkLWg2YTktODVnZS1nNjc4OTNoNmUwdGQ' 
	-H 'Content-Type: application/x-www-form-urlencoded'
	-d 'grant_type=client_credentials&scope=api-access'

The access_token parameter in the response includes an access token that is valid for one hour.

If you are a service provider, you can request an access token that allows you to make API requests on behalf of an account that you manage. For more information about access tokens, see Authentication.

Make an API Request

When you make an API request, include your access token in the Authorization header parameter and your API key in the WatchGuard-API-Key parameter. For example:

curl -X POST https://api.usa.cloud.watchguard.com/rest/authpoint/authentication/v1/accounts/ACC-1234567/resources/1234/authenticationpolicy
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA' \
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL' 
	-d '{
		"login": "jdoe",
		"originIpAddress": "198.51.100.98"
		}'

For more information about how to make requests to WatchGuard public APIs, see Make API Requests.