A small check-mark with a yellow gradient background
Thanks!
Someone from our team will reach out to you soon.
Oops! Something went wrong while submitting the form.
A black X

Authentication Parameters

Values that authenticate and represent a Producer to a Carrier.

When a producer requests a quote from a carrier, the carrier needs to confirm that the producer is appointed and authorized to sell the insurance product. In the real-world, a producers identity and appointment can be confirmed face-to-face or on the phone. At the API level, carriers tend to require a more abstracted form of authentication. These API level representations are submitted as [.h-code]auth_values[.h-code] when you connect a producer to a product.

Authentication Values are the values that a carrier uses to authenticate a producer's identity and appointment via API. Each product requires its own unique set of [.h-code]auth_values[.h-code] to authenticate a producer. An [.h-code]auth_values[.h-code] can be something as simple as the producer's username and password to log into the carrier's portal, confirming the appointment and authenticating the producer.

Here are some examples of Auth Parameters:

[.h-small-text](The auth parameter ids below are using a fake carrier name “Pigeon” in place of the actual carriers name)[.h-small-text]

auth_parameter_id Description
ath_sn37_pigeon_username A producers username to log into the Pigeon Carrier Portal
ath_nid9_pigeon_password A producers password to log into the Pigeon Carrier Portal
ath_byw7_pigeon_agent_id A producers UUID assigned by Pigeon

Authentication parameters are a similar concept to risk and coverage parameters, which is how information about an applicant is submitted on an application. Here are some examples of [.h-code]auth_values[.h-code].

‍

Using Authentication Parameters

When making a connection to give a producer access to a product, you need to include any relevant, required [.h-code]auth_values[.h-code] for the given product. These values should be submitted in an array of [.h-code]auth_values[.h-code], with each value corresponding to an [.h-code]auth_parameter_id[.h-code].

Each product requires its own set of authentication values based on the carriers way of authentication, and not all products require authentication values. This is because some carrier APIs authenticate a producer using the real-world representations that are required to create a producer, such as the producers [.h-code]email[.h-code]. These real-world representations are sent to the carrier by Herald and are not considered auth parameters.

If you want to build a front-end that allows producers to connect to a product, it’s important to make sure you require any relevant [.h-code]auth_values[.h-code] for that connection. All authentication values by product are documented in our Producers Connection Appendix. You can also get the required [.h-code]auth_values[.h-code] for a specific product dynamically by creating a Connection Intent.

[.icon-circle-blue][.icon-circle-blue] If you see that a product does not require authentication values, you can create a connection by submitting an empty array or omitting the [.h-code]auth_values[.h-code] array entirely.

Whether you are using the Producers Connection Appendix or creating a Connection Intent to get the required set of authentication values, you’ll see that there is additional data associated with each parameter. This additional data provides more details on each authentication parameter, and can be useful when collecting this information on a front-end. Every authentication parameter has the following metadata:

Property Type Description
auth_parameter_text Object Object containing descriptions and text for the parameter that you can render on a front-end.
→ name String The name of the auth parameter, which can act as the label of an input.
→ description String A detailed description of the auth parameter.
→ carrier_field String The name that the carrier uses for this field.
schema Object A JSON schema describing the expected value.
input_type String String meant to assist in customizing inputs beyond what is denoted by the JSON schema, e.g. 'short_text', 'long_text', 'address'.

‍

Complexities

Unlike risk and coverage parameters, authentication parameters contain little complexity.

  • Authentication parameters do not have conditional relationships: Unlike risk and coverage parameters, the set of auth_values required to connect to a product is static- their relevance does not change under certain circumstances.
  • Authentication parameters do not have parent/child relationships: Each [.h-code]auth_value[.h-code] is a representation of the producer directly.
  • Authentication parameters cannot have multiple values: Authentication values are used to authenticate with a carrier API when making a submission. For each authentication parameter, there can be only 1 value that represents the producer to the carrier.

While authentication parameters are generally less complex than risk and coverage parameters, it’s important to understand a few things:

  1. Herald cannot validate if a value is accurate: When making a connection, Herald checks to make sure that any required [.h-code]auth_values[.h-code] are submitted. However, Herald does not confirm that the value being submitted is an accurate representation of the producer. While a connection may have an [.h-code]active[.h-code] status, you can still receive an error when making a submission if the value is incorrect.
  2. A producer is authenticated as a member of their distributor and groups: While the [.h-code]auth_values[.h-code] you submit when making a connection are representations of the producer, similar values are used to represent the distributor and groups (if applicable) of a producer. Herald submits API level representations of the distributor and groups that the producer belongs to.

‍