Getting Started

Welcome to the Getting Started guide for the Webroot Unity API. This guide will walk you step-by-step through submitting an operation to the Unity API.


Step 1: Acquire Credentials

Please contact your Webroot representative to acquire credentials for accessing the Unity API. The following information will be required:

  • Username is the email address of the user.
  • Password is the password of the user.
  • Client Id is the unique id assigned to the client application.
  • Client Secret is the password for authorizing the client application.
  • Scope defines the set of operations an access token is permitted to request. The Unity API operation used as an example in this guide will require the SkyStatus.Site scope. See Service Extensions and Scopes for further details.

A valid site KeyCode will also be required to submit the Unity API operation that is used as an example in this Getting Started guide.

Note

The Unity API has independent environments for Beta and Production. Please ensure the credentials apply to the environment you would like to use.

Step 2: Setup REST Client

Setup a REST client to submit requests to the Unity API. Postman has been chosen to demonstrate the requests in this guide. Other REST clients may also be used.


Step 3: Get Access Token

Description

The Unity API implements the OAuth 2.0 protocol for user authentication and authorization. In OAuth 2.0 a client requests an access token on behalf of a user. The access token is used for granting access to Unity API operations. See the API Reference for a complete list of the available Unity API operations.

Submit the supplied credentials (as listed in Step 1: Acquire Credentials above) using the following request:

Method API Description
POST
Uses user credentials to obtain an access token

Note

The API URIs listed in the documentation are relative paths. The base URI for this environment is https://unityapi.webrootcloudav.com. Please append the base URI to the beginning of the API URI listed in the documentation to obtain the complete URI. For example, the complete URI for the authenticate request above is https://unityapi.webrootcloudav.com/auth/token.

The response of a successful request contains an access token and a matching refresh token. The access token is identified by the access_token field and the refresh token by the refresh_token field.

See Authentication for more information about the authentication process.

Using Postman

  1. Set the request method to POST and the URL to https://unityapi.webrootcloudav.com/auth/token. Then set the following request headers:

    • Set Accept to application/json
    • Set Content-Type to application/x-www-form-urlencoded
    • Set Authorization to use the HTTP Basic Authentication scheme for the client_id and client_secret. See the Request Description for more details.

    Postman Authenticate Headers
  2. Set the following body parameters and then press the Send button:

    • Set username to the email address of the user
    • Set password to the password of the user
    • Set grant_type to password
    • Setscope to SkyStatus.Site or *

    Postman Authenticate Body
  3. A successful request responds with an HTTP 200 (Ok) status code and the response body contains an access_token which will be used in the next step.

    Postman Authenticate Result

Step 4: Submit Unity API Operation

Description

After an access token has been obtained, make authorized requests to the Unity API by adding an Authorization header to each request as follows:

Authorization: Bearer {access token}

For the following sample operation submit the site KeyCode using the request below:

Using Postman

  1. Set the request method to GET and the URL to https://unityapi.webrootcloudav.com/service/api/status/site/{keyCode}. Then set the following request headers:

    • Set Accept to application/json
    • Set Content-Type to application/json
    • Set Authorization to Bearer {access token}

    Postman Operation Headers
  2. A successful request responds with an HTTP 200 (Ok) status code and the response body contains a JSON structure with the agent status information.

    Postman Operation Result

Troubleshooting

If the submitted access token has expired, the server responds with an HTTP 401 (Unauthorized) status code and the message "Error": "invalid_token". In this case a new access token needs to be obtained as described in Step 5: Refresh Access Token below.

If the submitted access token does not contain the scope required for the requested Unity API operation, the server responds with an HTTP 403 (Forbidden) status code and the message "Error": "insufficient_scope". In this case choose one of the following steps:

  • If the user has appropriate access rights for the scope required, obtain a new access token as described in Step 5: Refresh Access Token below. Ensure the required scope is specified in the scope URI parameter.
  • If the user does not have appropriate access rights for the required scope, please contact your Webroot representative to grant the access rights for the required scope.
See Service Extensions and Scopes for more information about the available scopes.


Step 5: Refresh Access Token

Description

A new access token can be requested if the current access token is invalid or has expired. The recommended approach is to use the refresh token returned in the response of Step 3: Get Access Token above as it does not require any user credentials. Submit the refresh token using the following request:

Method API Description
POST
Uses a refresh token to obtain an access token

The response of a successful request contains a new access token and matching refresh token.

Using Postman

  1. Set the request method to POST and the URL to https://unityapi.webrootcloudav.com/auth/token. Then set the following request headers:

    • Set Accept to application/json
    • Set Content-Type to application/x-www-form-urlencoded
    • Set Authorization to use the HTTP Basic Authentication scheme for the client_id and client_secret. See the Request Description for more details.

    Postman Authenticate Headers
  2. Set the following body parameters and then press the Send button:

    • Set refresh_token to {refresh token}
    • Set grant_type to refresh_token
    • Set scope to SkyStatus.Site or *

    Postman Authenticate Body
  3. A successful request responds with an HTTP 200 (Ok) status code. The response body contains an access_token which can be used to continue carrying out Unity API operations as in Step 4: Submit Unity API Operation. The response body also contains a new refresh_token so that this step can be repeated in the future.

    Postman Authenticate Result


Troubleshooting

If the submitted refresh token has expired or has become invalid, the server responds with a HTTP 400 (Bad Request) status code and the message "Error": "invalid_grant". In this case a new access and refresh token pair must be requested as described in Step 3: Get Access Token above.