Authorization API

Version: 1.1.1

Download the API specification

Introduction

The Authorization API is a RESTful API that you can use to return an audience parameter value for a WatchGuard Cloud account that you manage.

If you are a service provider and want to submit API requests on behalf of an account that you manage, you must include the audience value that identifies the managed account when you request an access token. For more information, see Authentication.

This API documentation explains how to get access to the Authorization API and includes examples to help you get started.

Get Started

This section describes how to submit requests to the Authorization API.

The Authorization API URL is:

https://{base API URL}/rest/platform/authorization/

The base URL for WatchGuard public APIs varies by region. The base API URL for your account appears on the Managed Access page in WatchGuard Cloud.

Endpoint Path Parameters

Each WatchGuard public API has a version, expressed as <major>.<minor>.<patch>. You specify the major API version, such as v1, as part of the endpoint URI path.

Authentication

WatchGuard public APIs use the Open Authorization (OAuth) 2.0 authorization framework for token-based authentication. To use the Authorization API, you must first enable API access in your WatchGuard Cloud account and make an API request to generate an access token.

You must include the access token and your API Key in the header of each request you make to the Authorization API.

For more information, see Authentication.

Request Headers

You must include this information in the header of each request you make to the Authorization API:

Content-Type

application/json

Accept

application/json

Authorization

The access token that you generate with the WatchGuard Authentication API. For more information, see Authentication.

WatchGuard-API-Key

The API Key associated with your WatchGuard Cloud account (shown on the Managed Access page in WatchGuard Cloud).

Return the Audience Parameter for a Managed Account

/{v1}/audiences

Returns the audience parameter value for a service provider or subscriber account that you manage.

You can use the audience parameter to get an access token that enables you to make API requests for the managed account. For more information, see Authentication.

Request Body

accountId
string
REQUIRED

The WatchGuard Cloud account ID of the managed account you want to make API requests for.

This must be the account ID of a service provider or subscriber account that you manage in WatchGuard Cloud.

To get the WatchGuard Cloud account IDs of the accounts you manage, you can make a request to the /{v1}/accounts/{accountid}/children endpoint in the Accounts API. For more information, see the Accounts API documentation.

Example: WGC-1-123abc456 or ACC-1234567

Example Request

This request returns the value of the audience parameter for the managed account with an account ID of WGC-1-64b54ce5655a75aabec2.

curl -X POST
	https://api.usa.cloud.watchguard.com/rest/platform/authorization/v1/audiences 
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA' \
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL' 
	-d '{
		"accountId": "WGC-1-64b54ce5655a75aabec2"
		}'

Example Response

The response includes the audience parameter for the managed account.

{
  "audience": "cd4b2ab4526e122cc89e4894b4f05be3"
}

This table shows and describes the data returned in the response:

audience
string

Audience value that identifies the specified managed service provider or subscriber account.

The value is empty if you request the audience parameter for your own account.

For delegated accounts, the audience value is valid until your access to the account expires or the client revokes your access. For other managed accounts, the audience value is valid as long as the account exists.

Example: cd4b2ab4526e122cc89e4894b4f05be3

If the accountId you specified in the request is not the account ID of an account you manage, the API returns a 401 Unauthorized error code.