Authentication

WatchGuard public APIs use the Open Authorization (OAuth) 2.0 authorization framework for token-based authentication. OAuth is an open standard that provides secure access to protected resources.

To request an access token, you send a request to the WatchGuard Authentication API. The request must include your read-write or read-only access credentials, encoded into base64. The string to encode must be in the form: AccessID:Password.

After you receive an access token, include the access token and your API key in the header of all requests to WatchGuard public APIs.

To download the WatchGuard Authentication API specification, after you enable API access in your WatchGuard Cloud account, click Download Authentication Spec.

Request an Access Token

To request an access token from the WatchGuard Authentication API, make a request to the /oauth/token endpoint in the Authentication API. The Authentication API URL appears on the Managed Access page in WatchGuard Cloud when API access is enabled.

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. To do this, you must include the audience parameter in the body of your request for an access token, and specify the value that identifies the managed account. To retrieve the audience parameter value for an account you manage, make a request to /{v1}/audiences endpoint in the Authorization API.

Some API endpoints include an accountID path parameter. To make an API request to these endpoints for an account that you manage, make sure that you specify the managed account ID in the accountID path parameter.

Request Headers

Content-Type
string
required

application/x-www-form-urlencoded

Authorization
string
required

The text "Basic" followed by a space and the credentials read-write access ID:read-write password encoded into base64.

Example: Basic dXNlcm5hbWU6N3loVHI1RHNkLWg2YTktODVnZS1nNjc4OTNoNmUwdGQ

Most programming languages include functions to encode base64 strings. You can also use online tools to encode text to base64.

Request Body

grant_type
string
required

The grant type value for the client credentials grant mechanism. The value must be client_credentials.

scope
string

The scope of the access request. If the request includes this parameter, the value must be api-access.

audience
string

The audience value that identifies the managed account you want to make API requests for.

Only include this parameter if you are a service provider and want to submit API requests for a WatchGuard Cloud account that you manage.

To get the audience value for a specific account, make a request to the /{v1}/audiences endpoint in the Authorization API. For more information, see Authorization API.

Example: cd4b2ab4526e122cc89e4894b4f05be3

Example Request

This example requests an access token for your own WatchGuard Cloud account:

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'

This example includes the audience parameter and requests an access token for an account that you manage:

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&audience=cd4b2ab4526e122cc89e4894b4f05be3'

Example Response

{
	"access_token": "eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA",
	"token_type": "Bearer",
	"expires_in": 3600,
	"scope": "api-access",
}

The response contains this information:

access_token string	The generated access token that is used to authorize your API requests. To prove your identity, you must include an access token in the header of all requests you make to WatchGuard public APIs. Use the token as the value of the `Authorization` parameter in the API request header. For more information, see Make Requests. If you are a service provider and the request included the `audience` parameter for an account you manage, you can use this access token to make requests for that account or your own account.
token_type string	The type of token generated. The value is always Bearer.
expires_in integer	The amount of time until the access token expires, in seconds. The value is always 3600.
scope string	The scope of the access request. The scope is always api-access.

Access Token Expiration

When you generate an access token, the token is valid for 3600 seconds (1 hour).

You can reuse the same token in public API requests until it expires, then you must request a new token. If you use an expired token in a request, the response contains the 401 Unauthorized status code.

Use one of these methods to determine when to request a new access token:

Keep track of the time since you received a token, and request a new token before the number of seconds in the expires_in field for the current token reaches zero.
Request a new token after you receive the 401 Unauthorized status code that indicates the current token is expired.

For more information about errors related to a specific public API, see the documentation for that API.