Authentication

Creating Credentials

You can generate new credentials within our Partner Portal by navigating to API Keys.

Basic Auth

Our API supports authentication with client credentials through the basic authorization scheme. Basic auth provides a simple way to authenticate machine-to-machine API calls utilizing your client credentials. The client credentials include a client-id and a client-secret which should be treated as a secret key and stored in a secure way. These credentials should not be utilized for frontend-based calls (e.g., via javascript in your customer-facing application).

Examples

cURL with user flags

curl -X GET -u $CLIENT_ID:$CLIENT_SECRET 'https://api.verticalinsure.com/v1/products' 

JavaScript

const request = await fetch('https://api.verticalinsure.com/v1/products', {
  headers: {
    Authorization: Basic btoa(`${CLIENT_ID}:${CLIENT_SECRET}`)
  }
})

Java

final OkHttpClient client = new OkHttpClient.Builder().authenticator((route, response) -> {
            String credential = Credentials.basic(clientId, clientSecret);
            return response.request().newBuilder().header("Authorization", credential).build();
        })
        .build();
final Response response = client.newCall(
        new Request.Builder()
                .url("https://api.verticalinsure.com/v1/products")
                .build()).execute();

PHP

$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.verticalinsure.com/v1/products',
    CURLOPT_USERPWD => $VERTICAL_INSURE_CLIENT_ID.":".$VERTICAL_INSURE_CLIENT_SECRET,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => array(
        'Accept: application/json'
    ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Python

response = requests.get(
    "https://api.verticalinsure.com/v1/products",
    auth=(VERTICAL_INSURE_CLIENT_ID,VERTICAL_INSURE_CLIENT_SECRET)
)

Ruby

uri = URI('https://api.verticalinsure.com/v1/products')

req = Net::HTTP::Get.new(uri)
req.basic_auth VERTICAL_INSURE_CLIENT_ID, VERTICAL_INSURE_CLIENT_SECRET

res = Net::HTTP.start(uri.hostname, uri.port) {|http|
  http.request(req)
}
puts res.body

C#

using System.Net.Http.Headers;
using System.Text;

using HttpClient client = new();
var basicAuthValue =
    Convert.ToBase64String(
        Encoding.ASCII.GetBytes($"{clientId}:{clientSecret}"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", basicAuthValue);

await GetProductsAsync(client);

static async Task GetProductsAsync(HttpClient client)
 {
     var json = await client.GetStringAsync(
         "https://api.verticalinsure.com/v1/products");
     Console.Write(json);
 }

Client Id Header

Our quoting API allows requests to include only the x-api-client-id header. This is the client_id part of your API credentials. This method ensures that your full API credentials remain secret while utilizing the Quote API from your user interface.

curl -X POST -H "x-api-client-id: $CLIENT_ID" 'https://api.verticalinsure.com/v1/quote/gap-medical'

Client-side Purchasing

We support an API to create a "customer client secret". A customer client secret is a short-lived credential whose scope is limited to a single customer email address. It can be used to purchase an insurance policy, but only for that email address, which means it is appropriate for use if you wish to perform the purchase on the client side.

The customer client secret must be created by authenticating to the API with a client ID and client secret, and the client secret must not be exposed on the client side, so a backend service is still required.

Here's an example of how you could use the customer client secret with a Django backend and a Javascript jQuery frontend. First, in your view, create the customer client secret and pass it to your template:

@login_required
def offer(request):
    email_address = "user@example.com"
    vi_customer_client_secret_response = requests.post(
        url="https://api.verticalinsure.com/v1/auth/customer/secret",
        auth=(VERTICAL_INSURE_CLIENT_ID,VERTICAL_INSURE_CLIENT_SECRET),
        json={"email_address": email_address},
    )
    vi_customer_client_secret_response.raise_for_status()
    vi_customer_client_secret = vi_customer_client_secret_response.json()["secret"]
    return render(
        request,
        "offer.html",
        {
            "vi_client_id": VERTICAL_INSURE_CLIENT_ID,
            "vi_customer_client_secret": vi_customer_client_secret,
            ...
        },
    )

Then, in your template, present the offer:

<gap-medical
    client-id="{{vi_client_id}}"
    customer-email-address="{{email_address}}"
    coverage-start-date={{coverage_start_date}}
    ...
    include-payment-element
></gap-medical>
<input id="vi-customer-client-secret" value="{{vi_customer_client_secret}}" hidden>

And in the Javascript handler for your 'purchase' or 'submit' button, retrieve the customer client secret and use it as a Bearer token when making your purchase request.

const component = document.querySelector("gap-medical");
component
  .validate()
  .then((validation) => {
    if (!validation.isValid) {
      throw Error("Credit card form validation failed!");
    }
    return component.getPaymentToken(creditCardHolderName, creditCardHolderZipCode);
  })
  .then((paymentToken) => {
    $.ajax({
      method: "post",
      url: "https://api.verticalinsure.com/v1/purchase/gap-medical",
      headers: {
        Authorization: "Bearer " + document.getElementById("vi-customer-client-secret").value,
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      data: JSON.stringify({
        quote_id: component.quoteId,
        payment_method: {
          token: paymentToken,
        },
      }),
    })
      .done(function () {
        alert("done");
      })
      .fail(function () {
        alert("failure");
      });
  });