Skip to main content

Establish Connection & Store Cookie

Garrick Guillory
Updated

Use this API process to authenticate with WebReports, establish a connection, and store the authentication cookie required for subsequent WebReports API calls.

The current WebReports example uses an Application Name and API Key to authenticate against:

extapi/APIAuthentication/Login

The returned authentication information is then used for later API requests.

Before You Begin

Before establishing the WebReports API connection:

  • Confirm that WebReports is accessible.
  • Confirm that you have the WebReports server URL.
  • Confirm that you have the correct Application Name.
  • Confirm that you have a valid API Key.
  • Confirm that the user or application has the required API access in WebReports.

The authentication information returned by this request is used by subsequent API calls. Store and handle it securely.

Authentication Endpoint

Use the following endpoint to authenticate with WebReports:

extapi/APIAuthentication/Login

This endpoint is used to submit the WebReports API authentication request.

What the Authentication Process Does

The authentication example performs the following actions:

  1. Creates the WebReports API authentication request.
  2. Supplies the Application Name and API Key.
  3. Sends the login request to WebReports.
  4. Stores the cookie returned by WebReports.
  5. Stores the Bearer token returned by the authentication response.
  6. Checks whether Multi-Factor Authentication (MFA) is required.
  7. Returns the authentication result.

VB.NET Example

The current WebReports example uses VB.NET to establish the connection and store the authentication information.

Con.cookieContainer = New CookieContainer
Con.handler = New Http.HttpClientHandler With {.CookieContainer = Con.cookieContainer, .UseDefaultCredentials = Con.DConnection.Trusted}
Con.client = New HttpClient(Con.handler)
Con.client.Timeout = TimeSpan.FromHours(24)
Dim Param = New APIAuthRequest With {
.Name = ApplicationName,
.Secret = APIKey
}
Dim URL As String = ""
URL = Con.DConnection.Server & "extapi/APIAuthentication/Login"
Dim Params As StringContent = New StringContent(JsonConvert.SerializeObject(Param, Formatting.Indented), Encoding.UTF8, "application/json")
Con.openResponse = Con.client.PostAsync(URL, Params).GetAwaiter().GetResult()
If Con.openResponse.IsSuccessStatusCode Then
Dim loginResponse = Con.openResponse.Content.ReadAsStringAsync().GetAwaiter().GetResult()
Dim loginInfo = JsonConvert.DeserializeObject(Of OktaToken)(loginResponse)
Con.client.DefaultRequestHeaders.Authorization = New Headers.AuthenticationHeaderValue("Bearer", loginInfo.AccessToken)
Con.cookieContainer.GetCookies(New Uri(URL))
If loginInfo.MFA Then
Return "MFA"
End If
Return "Success"
Else
Return Con.openResponse.Content.ReadAsStringAsync().GetAwaiter().GetResult()
End If

Authentication Results

The authentication response can produce different results.

Success

A successful authentication establishes the WebReports connection and provides the authentication information required for subsequent API calls.

The application should retain:

  • The authentication cookie
  • The Bearer token

These values are used when making later requests to the WebReports API.

MFA Required

If the response indicates that MFA is required, the authentication process must continue through the MFA workflow before API access is fully established.

The current example identifies this condition using an MFA response.

Authentication Error

If authentication is unsuccessful, review the returned response for information about the failure.

Common items to verify include:

  • WebReports URL
  • Application Name
  • API Key
  • API permissions
  • WebReports availability

Using the Stored Authentication

After authentication succeeds, use the stored cookie and Bearer token with subsequent WebReports API calls.

Do not establish a new connection for every individual request unless required by your integration.

If the authentication session expires or becomes invalid, authenticate again before making additional API calls.

Recommended Workflow

When using the WebReports API:

  1. Establish the WebReports connection.
  2. Store the returned authentication cookie.
  3. Store the Bearer token.
  4. Complete MFA if required.
  5. Make the required WebReports API calls.
  6. Re-authenticate if the stored session is no longer valid.

Troubleshooting

Authentication Fails

If WebReports does not authenticate the request:

  • Confirm that the WebReports server URL is correct.
  • Verify the Application Name.
  • Verify the API Key.
  • Confirm that the account or application has the required API permissions.
  • Confirm that WebReports is running and accessible.

Subsequent API Calls Are Not Authorized

If authentication succeeds but later API calls return authorization errors:

  • Confirm that the stored cookie is being included with the request.
  • Confirm that the Bearer token is being supplied correctly.
  • Verify that the authentication session has not expired.
  • Re-authenticate and retry the request if necessary.

MFA Is Required

If the response indicates MFA:

  • Complete the required MFA authentication process.
  • Do not proceed with other API calls until authentication is complete.

If the issue continues, contact BridgeWorks Support.

Related Articles

Related articles

Comments

0 comments

Please sign in to leave a comment.