Operator Management API

Version: 1.1.5

Introduction

The Operator Management API is a RESTful API that you can use to create, manage, and retrieve information about WatchGuard operators.

This API documentation explains how to get access to the Operator Management API and includes examples to help you get started. For detailed information about the Operator Management API endpoints, go to the API specification.

Get Started

This section describes how to submit requests to the Operator Management API.

The Operator Management API URL is:

https://{base API URL}/rest/platform/operator-mgmt/

The base URL for WatchGuard public APIs varies by region. You can see the base API URL for your account 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 Operator Management 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 Operator Management API. 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, see Authentication.

Request Headers

You must include this information in the header of each request you make to the Operator Management 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).

Create Operators

/{v1}/operators

Make a request to this endpoint to create new WatchGuard operators.

Request Body

username string REQUIRED	User name of the operator to create. This must be between 5 and 65 characters and can contain only letters, numbers, periods (.), hyphens (-), underscores (_) and plus signs (+). Example: mrodriguez
accountId string REQUIRED	The account ID of the WatchGuard account you want to create the operator in. When you submit a request to create multiple operators, you must specify the same account for each operator in the request. Example: WGC-1-123abc456
firstName string REQUIRED	First name of the operator. This can contain only alphanumeric characters. Example: Maria
lastName string REQUIRED	Last name of the operator. This can contain only alphanumeric characters. Example: Rodriguez
email string REQUIRED	Email address of the operator. Example: [email protected]
password string	Password of the operator. This must include at least 12 characters and contain all these character types: Lowercase letters Uppercase letters Numbers Symbols The password must not include <, >, emojis, or spaces. If you do not specify a password in the request, WatchGuard sends an email to the operator email address specified in the request body. The email includes a link to set a password. Example: 8N@43nwU7YUR
phone string REQUIRED	Phone number of the operator. This must be between 6 and 40 characters and can contain only numbers. Example: 2061234567
role string REQUIRED	Role to assign to the operator for the account. For Service Provider accounts, this can be one of these roles: OWNER SALES HELPDESK AUDITOR NO_ACCESS For Subscriber accounts, this can be one of these roles: ADMINISTRATOR ANALYST OBSERVER NO_ACCESS For more information about the permissions associated with each role, go to Manage WatchGuard Cloud Operators in WatchGuard Help Center. Example: ANALYST

Example Request

This request creates two new operators for account WGC-1-123abc456:

curl -X POST
	https://api.usa.cloud.watchguard.com/rest/platform/operator-mgmt/v1/operators
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA' 
	-H 'Content-Type: application/json'
	-H 'Accept: application/json'  
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-d [
	  {
	    "username": "mrodriguez",
	    "accountId": "WGC-1-123abc456",
	    "firstName": "Maria",
	    "lastName": "Rodriguez",
	    "email": "[email protected]",
	    "password": "9S674cdI9PRS",
	    "phone": "2061234567",
	    "role": "OWNER"
	  },
	{
	    "username": "schopra",
	    "accountId": "WGC-1-123abc456",
	    "firstName": "Seema",
	    "lastName": "Chopra",
	    "email": "[email protected]",
	    "password": "8N@43nwU7YUR",
	    "phone": "4251234567",
	    "role": "ANALYST"
	  }
	]

Example Response

The response includes a transaction ID and status information.

{
	"transaction_id": "4eb735c2-7640-4aw2-43a3-f429382b8bax",
	"status": "success",
	"message": "Add operators operation initiated."
}

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

transaction_id
string

Transaction ID.

To retrieve the status for a transaction, make a request to the /{v1}/TransactionStatus endpoint.

Example: 4eb735c2-7640-4aw2-43a3-f429382b8bax

status
string

Status of the transaction.

Example: success

message
string

Status message.

Example: Add operators operation initiated.

Update Operators

/{v1}/operators

Make a request to this endpoint to update existing WatchGuard operators.

Request Body

username string REQUIRED	User name of the operator to update. This must be between 5 and 65 characters and can contain only letters, numbers, periods (.), hyphens (-), underscores (_) and plus signs (+). Example: mrodriguez
accountId string REQUIRED	The account ID of the WatchGuard account you want to update the operator in. When you submit a request to update multiple operators, you must specify the same account for each operator in the request. Example: WGC-1-123abc456
firstName string	First name of the operator. This can contain only alphanumeric characters. Example: Maria
lastName string	Last name of the operator. This can contain only alphanumeric characters. Example: Rodriguez
phone string	Phone number of the operator. This must be between 6 and 40 characters and can contain only numbers. Example: 2061234567
role string	Role to assign to the operator for the account. For Service Provider accounts, this can be one of these roles: OWNER SALES HELPDESK AUDITOR NO_ACCESS For Subscriber accounts, this can be one of these roles: ADMINISTRATOR ANALYST OBSERVER NO_ACCESS If the current role of the user is OWNER or ADMINISTRATOR, you cannot assign a different role to the user. For more information about the permissions associated with each role, go to Manage WatchGuard Cloud Operators in WatchGuard Help Center. Example: ANALYST

Example Request

This request updates two operators for account WGC-1-123abc456:

curl -X PATCH
	https://api.usa.cloud.watchguard.com/rest/platform/operator-mgmt/v1/operators
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA' 
	-H 'Content-Type: application/json'
	-H 'Accept: application/json'  
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-d [
	  {
	    "username": "mrodriguez",
	    "accountId": "WGC-1-123abc456",
	    "phone": "2061234567"
	  },
	  {
	    "username": "schopra",
	    "accountId": "WGC-1-123abc456",
	    "role": "OBSERVER"
	  }
	]

Example Response

The response includes a transaction ID and status information.

{
	"transaction_id": "f4d29b6f-a352-476b-b191-579b97b0abee",
	"status": "success",
	"message": "Update operators operation initiated."
}

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

transaction_id
string

Transaction ID.

To retrieve the status for a transaction, make a request to the /{v1}/TransactionStatus endpoint.

Example: 4eb735c2-7640-4aw2-43a3-f429382b8bax

status
string

Status of the transaction.

Example: success

message
string

Status message.

Example: Update operators operation initiated.

Delete Operators

/{v1}/DeleteOperators

Make a request to this endpoint to delete WatchGuard operators.

Request Body

username
string
REQUIRED

User name of the operator to create. This must be between 5 and 65 characters and can contain only letters, numbers, periods (.), hyphens (-), underscores (_) and plus signs (+).

Example: mrodriguez

accountId
string
REQUIRED

The account ID of the WatchGuard account you want to delete the operator from.

When you submit a request to delete multiple operators, you must specify the same account for each operator in the request.

Example: WGC-1-123abc456

Example Request

This request deletes two operators for account WGC-1-123abc456:

curl -X POST
	https://api.usa.cloud.watchguard.com/rest/platform/operator-mgmt/v1/DeleteOperators
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA' 
	-H 'Content-Type: application/json'
	-H 'Accept: application/json'  
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-d [
	  {
	    "username": "mrodriguez",
	    "accountId": "WGC-1-123abc456",
	  },
	  {
	    "username": "schopra",
	    "accountId": "WGC-1-123abc456",
	  }
	]

Example Response

The response includes a transaction ID and status information.

{
	"transaction_id": "bd0bf122-d99a-4fe1-82ff-54c06f61e9c4",
	"status": "success",
	"message": "Delete operators operation initiated."
}

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

transaction_id
string

Transaction ID.

To retrieve the status for a transaction, make a request to the /{v1}/TransactionStatus endpoint.

Example: 4eb735c2-7640-4aw2-43a3-f429382b8bax

status
string

Status of the transaction.

Example: success

message
string

Status message.

Example: Delete operators operation initiated.

Get Transaction Status

/{v1}/TransactionStatus

Make a request to this endpoint to retrieve the status of a transaction.

Request Parameters

When you send a request to this endpoint, you must include this request parameter:

transaction_id
string
REQUIRED

Transaction ID.

Example: 4eb735c2-7640-4aw2-43a3-f429382b8bax

Example Request

This request returns the transaction status for the transaction ID 4eb735c2-7640-4aw2-43a3-f429382b8bax.

curl -X GET
	https://api.usa.cloud.watchguard.com/rest/platform/operator-mgmt/v1/TransactionStatus?transaction_id=4eb735c2-7640-4aw2-43a3-f429382b8bax
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA' 
	-H 'Accept: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

Example Response

The response includes information about the transaction.

{
  "status": "success",
  "transaction_status": [
    {
      "status": "FAILED",
      "username": "mrodriguez",
      "error": "Email address already exists."
    },	
    {
      "status": "SUCCESS",
      "username": "schopra"
    }
  ]
}

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

status string	Status of the transaction. Example: success
transaction_status array	Array that includes details for each operator in the transaction.
status string	Status of the transaction operation, such as operator creation. PENDING — Operation is in progress. SUCCESS — Operation completed successfully. FAILED — Operation failed. Example: FAILED
username string	User name of the operator. Example: mrodriguez
error string	If the status is FAILED, the error message associated with the operator account operation failure. Example: Email address already exists.

Get Operators for an Account

/{v1}/OperatorsByAccountId

Make a request to this endpoint to retrieve details of the operators for a WatchGuard Cloud account.

Request Parameters

When you send a request to this endpoint, you must include this request parameter:

account_id
string
REQUIRED

Account ID to return operators for.

Example: WGC-1-123abc456

Example Request

This request returns the operators for account ID WGC-1-123abc456.

curl -X GET
	https://api.usa.cloud.watchguard.com/rest/platform/operator-mgmt/v1/OperatorsByAccountId?account_id=WGC-1-123abc456
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA' 
	-H 'Accept: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

Example Response

The response includes information for the operators in the account.

{
  "result": [
    {
      "accountId": "WGC-1-123abc456",
      "email": "[email protected]",
      "firstName": "Maria",
      "lastName": "Rodriguez",
      "phone": "2061234567",
      "mfa": "Disabled",
      "userName": "mrodriguez"
    },
    {
    "accountId": "WGC-1-123abc456",
    "email": "[email protected]",
    "firstName": "Seema",
    "lastName": "Chopra",
    "phone": "4251234567",
    "mfa": "Disabled",
    "userName": "schopra"
   }
  ],
  "status": "success"
}

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

result array	Array that includes details for each operator in the account.
accountId string	The account ID of the WatchGuard account the operator belongs to. Example: WGC-1-123abc456
email string	Email address of the operator. Example: [email protected]
firstName string	First name of the operator. Example: Maria
lastName string	Last name of the operator. Example: Rodriguez
phone string	Phone number of the operator. This must be from 6 to 40 characters. Example: 2061234567
mfa string	MFA status of the operator. This can be Enabled or Disabled. Example: Disabled
userName string	User name of the operator. Example: mrodriguez
status string	Status of the request. Example: success