Description

The Webroot 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:

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.

Password Flow

The password credentials grant allows users to obtain an access token by providing their username and password directly, enabling applications to access their resources securely.

Authorization code flow

The Authorization Code grant type is used to exchange an authorization code for an access token.

After the user is redirected to the client via the redirect URI, the authorization code is obtained from the URI and used to request an access token.

Using Postman

1. In the Authorization tab for a collection or request, select OAuth 2.0 from the Type dropdown list.

2. Go to Configure New Token and provide below details in the required fields.

   • Set Callback URI(redirect URL) to IDP callback URI
   • Set Auth URI to IDP authorizePath
   • Set Access Token URI to IDP Access Token URI
   • Set Client ID to Unity provided client id
   • Set Client Secret to Unity provided client secret
   • Set Scope to IDP Scopes

   

3. Complete the fields with the required details, then click on the Get New Access Token button.

4. After successful validation of the client, the Unity AuthServer will display a list of available IDPs:

   

5. After successfully authenticating with the IDP, the Webroot API client page will prompt the user to grant the necessary permissions.

6. If the user is validated successfully, a new access token will be generated from the Identity Provider.

7. 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.

   

8. Copy the provided access token and send it to Webroot Unity API token request endpoint to exchange with Unity access token using token exchange flow.

Exchange the Subject Token for Unity Access Token and Refresh Token

With the Subject Token obtained, the application can now use it to acquire an unity access token and refresh token. The application initiates a POST request to the token endpoint.

Method	API	Description
POST	/auth/token	Uses client credentials and IDP's access token to obtain a new Unity access and refresh token.

Request Format (with "client_id" and "client_secret" in request body)

• application/x-www-form-urlencoded

/auth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=myTestApp&client_secret=mySecret&grant_type=token_exchange&subject_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IlB1a3l5UklObGVib1E1Q3FUXzQ5MkJnSFkwbyIsImtpZCI6IlB1a3l5UklObGVib1E1Q3FUXzQ5MkJnSFkwbyJ9.
eyJpc3MiOiJodHRwczovL2FjY291bnQuZGV2LmFwcHJpdmVyLmNvcnAvaWRlbnRpdHkiLCJhdWQiOiJodHRwczovL2FjY291bnQuZGV2LmFwcHJpdmVyLmNvcnAvaWRlbnRpdHkvcmVzb3VyY2VzIiwiZXhwIjoxNzI0NzM5MzY4LCJuYmYiOjE3MjQ3Mzg0NjgsImNsaWVudF9pZCI6IkFwcFJpdm
VyTmdpbnhVSUNsaWVudCIsInNjb3BlIjpbImVtYWlsIiwib3BlbmlkIiwiQm9zdW5DbGFpbXMiLCJvZmZsaW5lX2FjY2VzcyJdLCJzdWIiOiJhZG1pbkBtc3Bmb3JlbGRvcmFkb3Rlc3Rpbmd1bm8udGVzdCIsImF1dGhfdGltZSI6MTcyNDM5NDQwNCwiaWRwIjoiaWRzcnYiLCJDdXN0b21lcklEI
joiMTExMTUyIiwiZW1haWwiOiJhZG1pbkBtc3Bmb3JlbGRvcmFkb3Rlc3Rpbmd1bm8udGVzdCIsIlVzZXJDdWx0dXJlIjoiZW4tVVMiLCJQY21JRCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsIlBhcnRuZXJJRCI6IjExMTE1MiIsIkF1dGhWaWFDdXN0b21lcklkZW50
aXR5IjoidHJ1ZSIsIlVzZXJBY2NvdW50SUQiOiI0OWVkMjZiNC0yYjJmLTRjMjctOTM0NC1hNzRiMTZkZmMzYjkiLCJwaWQiOiI2ZmQ5NWRkNi0yNTczLTQ5NjMtOGY4Yi1iMGJiMDE0NGIzOTYiLCJjaWQiOiJiYTI0OGFkMC03MzljLTQ3NDctODVhNC1iMGJiMDE0NGIyMzEiLCJyb2xlIjpbIkN
VU1RPTUVSX0FETUlOIiwiQ1VTVE9NRVJfU1VQRVJBRE1JTiIsIkNVU1RPTUVSX1VTRVIiLCJQQVJUTkVSX0FETUlOIl0sImFtciI6WyJwYXNzd29yZCJdfQ.HQ7diss4FFulpbki-rry5Nneczihh1CpDNlBhgo7uRNjylV73xN7hjyO6zuMf7g7Od9YlgMmPJT2JBfae3MdpbYFpyWXcCIHocVRGe7
HW_aNCR0PddI50bXqpfVfv4uZpk6561mg9JU5cf4ST0Ary3jr87WqTNhdLTe0jqJyM46hQjsPVyGHrfKojvCPEJ5zRyk6JG3dxtgdOpk_0ivMV8HEch4goECwjkJHukk-g8wBjcqPQxQScBy1yLFR0eH23pDckR08YbTpkuDBuRXz7A6GOkPROF9tz7EVykXOjGktMKo8poDAtR6nhNmxlMi6BuYMi7ftl5r5SOOe49JI1w
&scope=SecureCloud.Usage&identity_provider=Zix
        

The token endpoint validates all parameters in the request, ensuring the subject token has not expired and matches the client ID and client secret. If successful, it generates an access token, refresh token and returns them in the response. With this access token, the application can now make API requests.

Response Format

• application/json, text/json

{
    "access_token": "-GOzYxdoL1M71taifS6vdMJBKGzipcOiKXSzK224UecsC96A_3G4QsmCRYWcagegS6EQ991ZocTFRdX2ziwbwmpQXfBv5NxLPGWDeb8ywJ-SpqJKEFeheOOXWRgs1AtTzxKSpfRVkY16FjK7bp72ij6YJJFdt-ktthFsy-zo-LTZTy3MikwFHihc8WXpgSOZBsoB-q5h2bqmXPXFA_DR9vMJTyAmiq8dhBanN_4gG1MbqAB0Ev4TyqgHkxjf2ED7PDiSpdyq2fuIEXjB4WwYayojYMjycI8OlftgC4D6-GfqmwdK_KoiihPdL9ZrhgeqRh-uKTEx96DwQoiTeVjR0xRHgCUzn_buayBKA_Cbsj1-vCgG6uwCeTbbfAqJuVCZ-2TcHw",
    "token_type": "bearer",
    "expires_in": 1843,
    "refresh_token": "8197863146a44317a1daa5ad0ac843f4",
    "scope": "[\"SecureCloud.Usage\"]"
}
        

Description

After an access token has been obtained, make authorized requests to the Webroot 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 URI 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}

   

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.

   

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 Webroot 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.

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:

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 URI 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.

   

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 *

   

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 Webroot Unity API operations as in Step 4: Submit Webroot Unity API Operation. The response body also contains a new refresh_token so that this step can be repeated in the future.

   

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.