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 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 connect their insurance account to your application.

Never send requests from your application’s client to the Axle API. Instead, make requests from your application’s protected services to avoid exposing your sensitive 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 application’s client. This token will be used to initialize Ignition and allows us to create secure, trackable session with your user. Ignition tokens do not expire.

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",
  "user": {"id": "usr_123456789"}
  }'

You can specify fields when generating an Ignition token to handle Ignition events (see the guide on Ignition events 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 and process Ignition events

Here are some common ways you can present Ignition to your application’s users:

  • Recommended: display Ignition at the right step within your application’s user experience (such as before booking a rental or closing a loan application) via an iframe or webview
  • Send Ignition URL in an asychronous user communication (such as email or push notification)

For guidance on specific implementations based on your application’s requirements, refer to the Initialize Ignition guide.

Then, process events generated during the course of the Ignition session. See the Ignition events guide for each Ignition event.

​
Step 3: Exchange tokens

Once the user successfully connects their account, you’ll receive an authorization code (authCode) as an Ignition event via redirect parameters, Window MessageEvent, or webhook.

However, for additional security (particularly if the Ignition event is delivered to your application’s client), you’ll need to exchange the short-lived authCode for a long-lived accessToken in your application’s protected services.

Each authCode expires 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, account identifier, and list of policy identifiers.

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, account identifier, and list of policy identifiers received in step 4 in your database - these values will 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 Policy

Now that you have an accessToken, you can retrieve the Policy object that was shared by the user by making a GET request to policies/{id} with the accessToken passed in the x-access-token header.

Request Sample: cURL
curl --request GET \
  --url https://api.axle.insure/policies/pol_CbxGmGWnp9bGAFCC-eod2 \
  --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": "pol_CbxGmGWnp9bGAFCC-eod2",
    "accountId": "acc_gM2wn_gaqUv76ZljeVXOv",
    "type": "auto",
    "carrier": "state-farm",
    "policyNumber": "123456789",
    "isActive": true,
    "effectiveDate": "2023-10-22T04:00:00.000Z",
    "expirationDate": "2024-10-22T04:00:00.000Z",
    "premium": "543.23",
    "address": {
      "addressLine1": "123 Fake St.",
      "addressLine2": "Unit 456",
      "city": "Atlanta",
      "state": "Georgia",
      "postalCode": "30315",
      "country": "USA"
    },
    "properties": [
      {
        "id": "prp_uSdzLVpi8c76H7kl6AQ-F",
        "type": "vehicle",
        "data": {
          "bodyStyle": "sedan",
          "vin": "WDDWJ8EB4KF776265",
          "model": "C 300",
          "year": "2019",
          "make": "Mercedes-Benz"
          "use": "commute"
        }
      }
    ],
    "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,
        "property": "prp_uSdzLVpi8c76H7kl6AQ-F"
      },
      {
        "code": "COLL",
        "label": "Collision",
        "deductible": 500,
        "property": "prp_uSdzLVpi8c76H7kl6AQ-F"
      }
    ],
    "insureds": [
      {
        "firstName": "John",
        "lastName": "Smith",
        "dateOfBirthYear": "1990",
        "licenseNo": "•••••1234",
        "licenseState": "GA",
        "type": "primary"
      },
      {
        "firstName": "Jane",
        "lastName": "Doe",
        "dateOfBirthYear": "1992",
        "licenseNo": "•••••5678",
        "licenseState": "GA",
        "type": "secondary"
      }
    ],
    "thirdParties": [
      {
        "name": "Super Leasing Trust",
        "type": "lessor",
        "address": {
          "addressLine1": "Po Box 105205",
          "addressLine2": null,
          "city": "Atlanta",
          "state": "GA",
          "postalCode": "30348"
        },
        "property": "prp_uSdzLVpi8c76H7kl6AQ-F"
      }
    ],
    "documents": [
      {
        "source": "carrier",
        "name": "Declaration Page",
        "type": ["declaration-page"],
        "url": "<signed-url>",
        "id": "doc_jd73dw6fn02sj28.pdf",
        "issuedDate": "2023-12-31T00:00:00.000Z",
        "effectiveDate": "2024-01-02T00:00:00.000Z",
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "modifiedAt": "2024-01-01T00:00:00.000Z",
    "refreshedAt": "2024-01-01T00:00:00.000Z"
  }
}

Well Done!

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