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.

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 Axle API credentials.

​
Step 1: Generate an Ignition token

Make a POST request to /ignition. 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"
}'

You can specify fields when generating an Ignition token to handle Ignition status updates (see Ignition Status Handling for more details) as well as attach user information or other metadata (see Start Ignition for more details).

Response Example
{
  "success": true,
  "data": {
    "ignitionToken": "ign_ur7EPeAa0km4wRlDrPJ4Z",
    "ignitionUri": "https://ignition.axle.insure/?token=ign_ur7EPeAa0km4wRlDrPJ4Z"
  }
}

​
Step 2: Initialize Ignition

Next, construct an Axle Ignition 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 Ignition authorization URL in a new window and setting up a route to handle the redirection parameters, or initialize the session within an iframe modal and listen for Window MessageEvent using window.addEventListener. See our guide on Ignition Status Handling for more details.

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 or in the body of the Window MessageEvent.

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.

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": {
    "account": "acc_gM2wn_gaqUv76ZljeVXOv",
    "policies": ["pol_CbxGmGWnp9bGAFCC-eod2"],
    "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": "acc_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",
        "premium": "543.23",
        "address": {
          "addressLine1": "123 Fake St.",
          "addressLine2": "Unit 456",
          "city": "Atlanta",
          "state": "Georgia",
          "postalCode": "30315",
          "country": "USA"
        },
        "coverages": [
          {
            "code": "BI",
            "label": "Bodily Injury",
            "limitPerPerson": 250000,
            "limitPerAccident": 500000
          },
          {
            "code": "PD",
            "label": "Property Damage",
            "limitPerAccident": 100000
          },
          {
            "code": "UMBI",
            "label": "Uninsured Bodily Injury",
            "limitPerPerson": 100000,
            "limitPerAccident": 300000
          },
          {
            "code": "COMP",
            "label": "Comprehensive",
            "deductible": 500
          },
          {
            "code": "COLL",
            "label": "Collision",
            "deductible": 500
          }
        ],
        "properties": [
          {
            "type": "vehicle",
            "data": {
              "bodyStyle": "sedan",
              "vin": "WDDWJ8EB4KF776265",
              "model": "C 300",
              "year": "2019",
              "make": "Mercedes-Benz"
            }
          }
        ],
        "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"
          }
        ],
        "thirdParties": [],
        "documents": [],
        "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!

Be sure to visit the full 📖 API Reference to learn more about each endpoint and resource!

ChangelogAxle for Platforms