API Authentication

In general, all API callers must authenticate with the server and pass authorization requirements before the API request is executed by the server.

Note: The /clients/{clientId}/sessions API does not require authentication or authorization as it is used to initiate a session from an anonymous user.

Authenticate from Interactive API

When you use the interactive API to submit API requests to the server, the authentication details for each API request are populated by the interactive tool.

When using the interactive API, authentication works in the following way:
  1. A user with the REST API Documentation View and the Administrator role accesses the interactive API.
  2. The user enters authorization details in the Available Authorizations dialog.
    Users have the option to authorize with the following options:
    Basic authentication
    A valid InsuranceNow username and password provide authentication.
    JWT
    An Okta-provided JWT provides authentication.
    OAuth2
    An internally configured swagger-api client is used to obtain a JWT. In this case, InsuranceNow is the identity provider.
    Note: From the interactive API, the OAuth2 option must only be used for testing purposes.
    The authentication details apply to all API calls submitted from the interactive API for the current session unless the user selects a different authentication method.
  3. The user selects an API to try, enters the required parameters, and executes the API request. Before the request is executed by the server, the server validates the authorization details.

Authenticate from a Consumer Sales Portal

The Consumer Sales Portal uses a JWT from Okta to authenticate with InsuranceNow. When a consumer sales portal submits API requests to the server, the following steps occur:

When a consumer service portal user has not logged in:

  1. Portal submits the POST /clients/{clientId}/sessions API endpoint.
  2. InsuranceNow requests an Okta-issued JWT through the Guidewire Hub.
  3. As requests from the Consumer Sales Portal are anonymous, Okta generates a JWT for the directportal user.
  4. InsuranceNow includes the Okta-issued JWT in the API response.
  5. The portal includes the Okta-issued JWT in HTTP authorization header of each API request for that session.
  6. InsuranceNow validates the Okta-issued JWT prior to executing each API request. For more information, see Manage access to quote.

When a consumer service portal user has logged in:

  1. Okta generates a JWT upon user login.
  2. The portal included the Okta-issued JWT in HTTP authorization header of each API request for that session.
  3. InsuranceNow validates the Okta-issued JWT prior to executing each API request.

Authenticate from an Agent Portal

API requests from an Agent Portal authenticate with the server using OAuth2. When the Agent Portal submits API requests to the server, the following steps occur:
  1. The Agent Portal uses OAuth2 to authenticate with the server as the InsuranceNow agent user.
  2. The identity provider generates a JWT for the InsuranceNow agent user using OAuth2.
  3. The Agent Portal includes the JWT in the HTTP authorization header of each API request.

For the steps to configure Agent Portal authentication, see Agent Portal authentication.

Authenticate from a Consumer Service Portal

The Consumer Service Portal uses a JWT from Okta to authenticate with InsuranceNow. JWT client authentication requires that InsuranceNow is configured with the required settings and credentials to request and decode a JWT from Okta.

There are 2 modes when a consumer service portal submits API requests to the server:
  1. When a consumer service portal user has not logged in:
    1. Portal submits the POST /clients/{clientId}/sessions API endpoint.
    2. Portal submits the POST /clients/{clientId}/sessions API endpoint.
    3. InsuranceNow requests an Okta-issued JWT through the Guidewire Hub.
    4. Okta generates a JWT for the portal user.
    5. InsuranceNow includes the Okta-issued JWT in the API response.
    6. The portal includes the Okta-issued JWT in HTTP authorization header of each API request for that session.
    7. InsuranceNow validates the Okta-issued JWT prior to executing each API request.
  2. When a consumer service portal user has logged in:
    1. Okta generates a JWT upon user login.
    2. The portal included the Okta-issued JWT in HTTP authorization header of each API request for that session.
    3. InsuranceNow validates the Okta-issued JWT prior to executing each API request.