Find the desired product help

Web Protection API Authentication



Web Protection API uses OAuth 2 with Proof Key for Code Exchange (PKCE) for authentication. PKCE is an additional layer in the OAuth 2.0 Authorization Code Flow and provides better security for use in applications that can not store a client secret, such as single-page applications.

Full Web Protection API documentation is available at <Need to add URL>.

With PKCE, a code verifier and a code challenge are used when exchanging the authorization code for an access token, replacing the client secret used in OAuth1. 
See https://www.rfc-editor.org/rfc/rfc7636  for more information on PKCE.

The following are the authentication steps to get an access token which can then be used to call Web Protection API endpoints. Examples shown use the Postman API client. See https://www.postman.com

  • Create the three parameters required in the initial authorization call to Web Protection that are self-generated: state, code_verifier and code_challenge:
    • code_verifier: This is a random 128 character string created by you. It can be generated using an online tool such as http://www.unit-conversion.info/texttools/random-string-generator.

      For example: qJainvnXruMEcECKUTf1Zt4ZnxDN0cw6MV8pXzK1EQ5Bze6YOyTyMTuQ3sWm6t0CTpWlNZGHZxvVwz23fsAfakVigCVd6jFswK9nbeQ4EuLPvdGvnw5JDmrv2esFu75S
    • code_challenge: This is a SHA-256 encoded parameter generated by you using the code_verifier created in the previous step. To do this, submit the code_verifier in an online tool such as https://tonyxu-io.github.io/pkce-generator.

      For example: 9tanTO36l9r-gHOKK6fa_0TzCLMmMA5989OVxEugerQ
  • Make the oauth2 call to Web Protection to request an access token.

    Format: GET https://your-API-URL.Web Protectioncloud.com:8443/restapi/oauth/authorize

    The following GET and Basic Auth parameters are required to make the call:

     Parameter   Description   Example 
     response_type   This is always "code".   code
     client_id   This is always "2".  2
     code_challenge   An SHA-256 encoded code_verifier (see Step 1).   9tanTO36l9r-gHOKK6fa_0TzCLMmMA5989OVxEugerQ
     code_challenge_method   S256  S256
     state  This is a self-generated random 40 character string that you create (see Step 1).   123xkYFwY2qiG7dEb7Cq1z74QNFnmioh5aNcOrRH
     code_verifier   A self generated 128 character string that you create (see Step 1).  qJainvnXruMEcECKUTf1Zt4ZnxDN0cw6MV8pXzK1EQ5 

     Bze6YOyTyMTuQ3sWm6t0CTpWlNZGHZxvVwz23fsAf 

     akVigCVd6jFswK9nbeQ4EuLPvdGvnw5JDmrv2esFu75S 
     redirect_uri   The exact Web Protection URL that you are calling to, with port number, followed by   /restapi/oauth/callback
     
     See Web Protection API URLs to determine your API URL.    		  https://your-API-URL.Web   Protectioncloud.com:8443/restapi/oauth/callback

     See Web Protection API URLs to determine your API URL.
     code (optional)   This parameter is only required if 2FA is enabled on your Web Protection. It is the 6 digit code from your authenticator app.  384 519

    The following Basic Auth parameters must also be passed:

     Parameter   Description    Example 
     Username  Your Web Protection username   admin@yourcompany.com
     Password  Your Web Protection password   6*4iw48Xkg3M

    Using the examples above, the complete request looks as follows in Postman:

  • An access token is returned, which displays in Postman as follows below. Select and copy the access token.
  • Once copied, this can then be used for authorization when calling other endpoints. In Postman, this is specified in the Authorization tab as shown below. The token type is Bearer Token.