This is where Ignition - Axle’s consumer facing consent widget - comes into play. This guide will walk you through setting up Ignition, obtaining access tokens, and making API requests against the Axle API.

How it works Axle provides a consistent, single point integration to connect your users’ insurance accounts to your application. To do so, Axle closely follows the OAuth 2.0 Authorization Code flow which begins when your user wants to link their insurance account to your application.

​
Step 1: Create an Ignition token

Make a POST request to /ignition with a redirect url - the URL we’ll redirect the user to after linking their account - and optionally a webhook url. In return, you’ll retrieve an ignitionToken which you’ll need to pass to your app’s client. This token will be used to initialize Ignition and allows us to create secure, trackable session with your user.

Request Sample: cURL
curl --request POST \
  --url https://api.axle.insure/ignition \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: cli_mZj6YGXhQyQnccN97aXbq' \
  --header 'x-client-secret: RZM-5BErZuChKqycbCS1O' \
  --data '{
  "redirectUri": "https://example.com/insurance/success",
  "webhookUri": "https://example.com/webhook"
}'
Response Example
{
  "success": true,
  "data": {
    "ignitionToken": "ign_ur7EPeAa0km4wRlDrPJ4Z",
    "ignitionUri": "https://ignition.dev.axle.insure/?token=ign_ur7EPeAa0km4wRlDrPJ4Z"
  }
}

Never send requests from your client to the Axle API. Establishing a session server side allows us to create a secure session without exposing your credentials.

​
Step 2: Initialize Ignition

Next, construct an Axle authorization URL using https://ignition.axle.insure?token={ignitionToken} for production and https://ignition.sandbox.axle.insure?token={ignitionToken} for development.

Now that you’ve constructed an Axle authorization URL you can open an Ignition authentication session for the user to link their account:

  • On iOS, we suggest leveraging Apple’s natively supported ASWebAuthentication session (full documentation)
  • On Android, we suggest using Chrome Custom Tabs (full documentation) to create an in-app session and Android App Links (full documentation) to deep-link back into your application.
  • On web, we suggest simply directing the user to the Axle authorization URL and setting up a route to handle the redirection parameters, or initialize the session within an iframe modal and listen for redirect attempts (e.g., using Window.postMessage()).

Congrats!

At this stage the user will now be able to securely link their insurance account to Axle 🎉.

​
Step 3: Exchange tokens

Once the user successfully links their account, you’ll receive an authorization code as a query parameter at the redirectUri you provided in step 1.

However, data sent by a client - especially via URLs - is generally considered insecure. That’s where the OAuth 2.0 Authorization Code grant comes into play. We’ll exchange the short-lived authCode for a long-lived accessToken server side. You can read more about OAuth 2.0 authorization code grants here.

authCodes expire after 10 minutes so be sure you’re exchanging codes in real time.

To do so, make a POST request with your authCode to token/exchange. In return you’ll receive an accessToken and an accountId.

Request Sample: cURL
curl --request POST \
--url https://api.axle.insure/token/exchange \
--header 'Content-Type: application/json' \
--header 'x-client-id: cli_mZj6YGXhQyQnccN97aXbq' \
--header 'x-client-secret: RZM-5BErZuChKqycbCS1O' \
--data '{
"authCode": "cod_LGUgD5ZnqWy3pThdOLUsT"
}'
Response Example
{
  "success": true,
  "data": {
    "accountId": "acc_gM2wn_gaqUv76ZljeVXOv",
    "accessToken": "tok_IwShXCT_JPr6rmtiCVxcQ"
  }
}

​
Step 4: Store access credentials

Store the accessToken and accountId received in step 4 in your database - they’ll be used to access account and policy information for the user going forward.

Congrats!

You have now received an accessToken that represents consent from the user and can now leverage the Axle API to access their insurance data 🎉🎉!

​
Step 5: Retrieve the Account

Now that we have an accessToken, we can retrieve the Account object for the user’s linked account by making a GET request to accounts/{id} with the accessToken passed in the x-access-token header. By passing the expand parameter, we can also can retrieve all Policy objects available on the account:

Request Sample: cURL
curl --request GET \
  --url https://api.axle.insure/accounts/acc_gM2wn_gaqUv76ZljeVXOv?expand=true \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: tok_IwShXCT_JPr6rmtiCVxcQ' \
  --header 'x-client-id: cli_mZj6YGXhQyQnccN97aXbq' \
  --header 'x-client-secret: RZM-5BErZuChKqycbCS1O'
Response Example
{
  "success": true,
  "data": {
    "id": "acc_gM2wn_gaqUv76ZljeVXOv",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@grr.la",
    "carrier": "state-farm",
    "policies": [
      {
        "id": "pol_CbxGmGWnp9bGAFCC-eod2",
        "accountId": "gM2wn_gaqUv76ZljeVXOv",
        "type": "auto",
        "carrier": "state-farm",
        "policyNumber": "123456789",
        "isActive": true,
        "effectiveDate": "2021-10-22T04:00:00.000Z",
        "expirationDate": "2022-10-22T04:00:00.000Z",
        "address": {
          "addressLine1": "123 Fake St.",
          "addressLine2": "Unit 456",
          "city": "Atlanta",
          "state": "Georgia",
          "postalCode": "30315",
          "country": "USA"
        },
        "coverages": [
          {
            "limitPerPerson": 250000,
            "code": "BI",
            "label": "Bodily Injury Liability",
            "limitPerAccident": 500000
          },
          {
            "code": "PD",
            "label": "Property Damage Liability",
            "limitPerAccident": 100000
          },
          {
            "limitPerPerson": 100000,
            "code": "UMBI",
            "label": "Uninsured Bodily Injury Liability",
            "limitPerAccident": 300000
          },
          {
            "code": "COMP",
            "label": "Comprehensive",
            "deductible": 375
          },
          {
            "code": "COLL",
            "label": "Collision",
            "deductible": 375
          }
        ],
        "properties": [
          {
            "type": "vehicle",
            "data": {
              "bodyStyle": "sedan",
              "vin": "WDDWJ8EB4KF776265",
              "model": "C 300",
              "year": "2019",
              "make": "Mercedes-Benz"
            },
            "lienholders": []
          }
        ],
        "insureds": [
          {
            "firstName": "John",
            "lastName": "Smith",
            "dateOfBirthYear": "1990",
            "licenseNo": "•••••1234",
            "licenseState": "GA",
            "licenseStatus": "Valid",
            "type": "Primary"
          },
          {
            "firstName": "Jane",
            "lastName": "Doe",
            "dateOfBirthYear": "1992",
            "licenseNo": "•••••5678",
            "licenseState": "GA",
            "licenseStatus": "Valid",
            "type": "Secondary"
          }
        ],
        "createdAt": "2022-01-01T00:00:00.000Z",
        "modifiedAt": "2022-01-01T00:00:00.000Z",
        "refreshedAt": "2022-01-01T00:00:00.000Z"
      }
    ],
    "connection": {
      "status": "active",
      "updatedAt": "2022-01-01T00:00:00.000Z"
    },
    "createdAt": "2022-01-01T00:00:00.000Z",
    "modifiedAt": "2022-01-01T00:00:00.000Z",
    "refreshedAt": "2022-01-01T00:00:00.000Z"
  }
}

Well Done!

Now that you can access the Axle API, be sure to visit the full 📖 API Reference to see what endpoints and objects are available.

ChangelogOverview