Accounts API
Version: 1.4.1
Download the API specification
Introduction
The Accounts API is a RESTful API that you can use to manage and get information about accounts.
This API documentation explains how to get access to the Accounts API and includes examples to help you get started.
Get Started
This section describes how to submit requests to the Accounts API.
The Accounts API URL is:
https://{base API URL}/rest/platform/accounts/
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.
All Accounts API endpoint URIs must include your WatchGuard Cloud account ID in the {accountid}
path parameter.
Authentication
WatchGuard public APIs use the Open Authorization (OAuth) 2.0 authorization framework for token-based authentication. To use the Accounts 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 Accounts API.
For more information, see Authentication.
Request Headers
You must include this information in the header of each request you make to the Accounts 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). |
Get Account Information
/{v1}/accounts/{accountid}
Make a request to this endpoint to get information about an account. If you want to retrieve specific information, include the fields
request parameter.
Path Parameters
When you send a request to this endpoint, you must include these path parameters:
accountId
|
Your WatchGuard Cloud account ID. You can see your Example: WGC-1-123abc456 or ACC-1234567 |
Request Parameters
When you send a request to this endpoint, you can include these request parameters:
fields
|
Enables you to specify what information to return for the WatchGuard Cloud account. You can request this information:
For example, the query string |
Example Request
This request returns information about account ID ACC-1234567, and includes the contacts and addresses for the account.
curl -X GET
https://api.usa.cloud.watchguard.com/rest/platform/accounts/v1/accounts/ACC-1234567?fields=contacts,addresses
-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
-H 'Content-Type: application/json'
-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
Example Response
The response includes information about the account.
{
"accountInfo": {
"accountId": "ACC-1234567",
"addresses": {
"billingAddress": {
"address1": "1234 North Street",
"address2": null,
"addressId": 1,
"city": "Seattle",
"state": "WA",
"country": "United States",
"postalCode": "98104",
}
"mailingAddress": {
"address1": "1234 North Street",
"address2": null,
"addressId": 1,
"city": "Seattle",
"state": "WA",
"country": "United States",
"postalCode": "98104",
}
},
"contacts": [
{
"email": "[email protected]",
"firstName": "Yasmine",
"lastName": "Iqbal",
"phone": "1237654",
"primaryContactId": 61
}
],
"delegatedParent": null,
"name": "Example Company",
"parent": null,
"serviceProperties": null,
"status": 1,
"type": 3,
}
}
This table shows and describes the data returned in the response:
name
|
Name of the account. Example: Example Company |
status
|
The status of the account.
Example: 1 |
contacts
|
Contacts for the account. |
primaryContactId
|
Contact ID. |
firstName
|
First name of the primary contact. |
lastName
|
Last name of the primary contact. |
email
|
Email address of the primary contact. |
phone
|
Phone number of the primary contact. |
delegatedParent
|
Information about the Service Provider that manages the account, if the account has been delegated. For more information about account delegation, see the WatchGuard Cloud Help. |
id
|
Account ID of the Service Provider that manages this delegated account. Example: WGC-1-123abc456 or ACC-1234567 |
expirationDate
|
Date that delegated access ends. |
name
|
Name of the Service Provider account that manages this delegated account. |
phone
|
Phone number of the Service Provider account that manages this delegated account. |
email
|
Email address of the Service Provider account that manages this delegated account. |
addresses |
Addresses of the account. |
mailingAddress |
Mailing address of the account. |
address1
|
Primary street address. |
address2
|
Secondary street address. |
city
|
City name. |
state
|
State or province. |
country
|
Country name. |
postalCode
|
Zip or postal code. |
billingAddress |
Billing address of the account. |
address1
|
Primary street address. |
address2
|
Secondary street address. |
city
|
City name. |
state
|
State or province. |
country
|
Country name. |
postalCode
|
Zip or postal code. |
serviceProperties |
|
ssourlname
|
Identifier for SSO. |
accountId
|
WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567 |
type
|
Type of WatchGuard Cloud account.
Example: 1 |
parent |
Parent account information. |
id
|
Account ID of the Service Provider that manages this tenant account. Example: WGC-1-123abc456 or ACC-1234567 |
access
|
Parent access to child accounts. |
Create a New Account
/{v1}/accounts/{accountId}
Make a request to this endpoint to add a new managed account.
Path Parameters
When you send a request to this endpoint, you must include these path parameters:
accountId
|
Your WatchGuard Cloud account ID. You can see your Example: WGC-1-123abc456 or ACC-1234567 |
Request Body
type
|
Type of account to create. Specify one of these values:
Example: 2 |
name
|
Name of the new account. Example: NewAccount |
firstName
|
First name of the primary contact. Example: Yasmine |
lastName
|
Last name of the primary contact. Example: Iqbal |
email
|
Email address of the primary contact. Example: [email protected] |
Example Request
This request returns the account ID of the new account.
curl -X POST
https://api.usa.cloud.watchguard.com/rest/platform/accounts/v1/accounts/ACC-1234567
-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA' \
-H 'Content-Type: application/json'
-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
-d '{
"type": 2,
"name": "NewAccount",
"firstName": "Yasmine",
"lastName": "Iqbal",
"email": "[email protected]"
}'
Example Response
The response includes an array that includes the new account ID.
{
"accountID": "WGC-1-123abc456"
}
This table shows and describes the data returned in the response:
accountId
|
WatchGuard Cloud account ID of the newly created account. Example: WGC-1-123abc456 |
Get Managed Accounts
/{v1}/accounts/{accountId}/children
Make a request to this endpoint to get a list of all your managed accounts. If you want to retrieve only specific accounts, you can include request parameters.
Path Parameters
When you send a request to this endpoint, you must include these path parameters:
accountId
|
Your WatchGuard Cloud account ID. You can see your Example: WGC-1-123abc456 or ACC-1234567 |
Request Parameters
When you send a request to this endpoint, you can include these request parameters:
type
|
Specifies the type of account to return. This can be one of these values:
|
sortBy
|
Sorts the results by account name or account type.
|
sortOrder
|
Sorts the results in ascending or descending order.
|
offset
|
Specifies the index of the first account to include in the results. |
limit
|
Sets the number of accounts to show on each page. A value of -1 shows all records. |
name
|
Searches for accounts with a specific account name. |
includeDelegatedAccounts
boolean |
Specifies whether to retrieve delegated accounts. This can be one of these values:
Default value: false |
Example Request
This request returns a list of the managed accounts for account ID ACC-1234567.
curl -X GET
https://api.usa.cloud.watchguard.com/rest/platform/accounts/v1/accounts/ACC-1234567/children
-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA' \
-H 'Content-Type: application/json'
-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
Example Response
The response includes an array that includes all of the managed accounts for account ID ACC-1234567. The managed accounts of each Service Provider are also shown.
{
"items": [
{
"accountId": "WGC-1-123abc456",
"childrenList": [],
"name": "California",
"parentAccess": "false",
"relationName": "Inherited",
"relationType": "Inherited",
"totalOperators": 2,
"type": 2,
},
{
"accountId": "WGC-1-321cba654",
"childrenList": [
{
"accountId": "WGC-1-987abc654",
"childrenList": [],
"name": "Maine",
"parentAccess": "false",
"relationName": "Inherited",
"relationType": "Inherited",
"totalOperators": 3,
"type": 2,
},
],
"name": "Washington",
"parentAccess": "false",
"relationName": "Inherited",
"relationType": "Inherited",
"totalOperators": 1,
"type": 1,
}
]
"pageControls": {
"limit": 3,
"offset": 0,
"totalItems": 3
}
}
This table shows and describes the data returned in the response:
items
|
List with information about your managed accounts. |
accountId
|
WatchGuard Cloud account ID of the managed account. Example: WGC-1-123abc456 |
name
|
Name of the managed account. Example: California Company |
type
|
Type of WatchGuard Cloud account and whether it is a tier-1 account or a tier-n account.
Example: 1 |
parentAccess
|
Whether the Service Provider has access to the managed account. |
relationName
|
Name of the relationship between the Service Provider and managed account. |
relationType
|
Relationship between the Service Provider and the managed account. |
totalOperators
|
Number of operators the account has. |
childrenList
|
Managed accounts of Service Providers. |
pageControls
|
Settings that specify how to paginate search results. |
limit
|
Number of accounts shown per page. |
offset
|
Index of the first account included in the results. |
totalItems
|
Total number of managed accounts. |
Make a request to this endpoint to add a managed account.
Delete Managed Accounts
/{v1}/accounts/{accountId}
Make a request to this endpoint to delete your managed accounts.
Path Parameters
When you send a request to this endpoint, you must include these path parameters:
accountId
|
Your WatchGuard Cloud account ID. You can see your Example: WGC-1-123abc456 or ACC-1234567 |
Request Parameters
When you send a request to this endpoint, you can include this request parameter:
force
|
Specifies whether to delete the account if it manages other accounts. This can be one of these values:
Default value: false Example: force=true |
Example Request
This request returns a list of the deleted accounts for account ID ACC-1234567.
curl -X DELETE
https://api.usa.cloud.watchguard.com/rest/platform/accounts/v1/accounts/ACC-1234567/force=true
-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA' \
-H 'Content-Type: application/json'
-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
Example Response
The response includes an array that includes all of the deleted accounts for account ID ACC-1234567.
{
"childIds": [
" WGC-1-123abc456",
" WGC-1-123abc457"
]
}
This table shows and describes the data returned in the response:
childIds
|
WatchGuard Cloud account ID of the deleted account. Example: WGC-1-123abc456 |
Update Managed Accounts
/{v1}/accounts/{accountId}
Make a request to this endpoint to update your managed accounts.
Path Parameters
When you send a request to this endpoint, you must include these path parameters:
accountId
|
Your WatchGuard Cloud account ID. You can see your Example: WGC-1-123abc456 or ACC-1234567 |
Request Body
name
|
Name of the updated account. Example: UpdatedAccount |
firstName
|
First name of the primary contact. Example: Yasmine |
lastName
|
Last name of the primary contact. Example: Iqbal |
email
|
Email address of the primary contact. Example: [email protected] |
Example Request
This request updates the specified managed account. Example: WGC-1234567.
curl -X PATCH
https://api.usa.cloud.watchguard.com/rest/platform/accounts/v1/accounts/WGC-1234567
-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA' \
-H 'Content-Type: application/json'
-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
-d '{
"name": "UpdatedAccount",
"firstName": "Yasmine",
"lastName": "Iqbal",
"email": "[email protected]"
}'
Example Response
A successful request returns the 204 No Content
status code.