Root's APIs support flexible authentication mechanisms to let your services securely access our resources, whether you’re using an integration secret key, a generated agency access token, or a legacy API key. This section outlines how authentication works, what to expect, and how to handle common scenarios.

Authenticating with any auth token

Regardless of the type of auth token being used, any auth token must be provided as a bearer token included in the Authorization header of every request:

Authorization: Bearer <your-auth-here>

Make sure to store this token securely. Please, do not share it in plaintext with your front-end clients or commit it to version control. If you suspect that an auth token has been exposed, please notify your Root representative, and they can help revoke the existing auth token and reissue a new one.

Types of Auth Tokens

Root's APIs support three different types of auth tokens:

• Integration secret key
• Agency access token
• Legacy API key

See below for more information about each type of auth token.

Integration Secret Key

An integration secret key is an auth token which is scoped to your particular integration. Today, it is only used for our "Create token" endpoint, which is used to generate agency auth tokens (see below for more details on that auth token type).

This type of auth token will always begin with: isk_.

Security Incident Response

If you suspect that your integration secret key has been exposed, please reach out to your Root representative immediately.

If your integration secret key was exposed, or you are unsure, your Root representative will revoke that key's access to Root's APIs.

In this case:

• All agency access tokens generated for all agencies with access to your integration stop working immediately.
• Your current integration secret key will also stop working immediately.
• We will generate a new integration secret key for your integration.
• You will be able to generate new agency access tokens with your new integration secret key, using our "Create token" endpoint.

Agency Access Token

If your integration serves multiple auto insurance agencies, Root provides an auth API which can be used to generate a temporary access token for a particular agency. This ensures that you only have to manage one integration secret key. Please, refer to our "Create token" endpoint for more details.

Note: You will receive a 401 not authorized response if you use an auth token which is not authorized for this action. Only active integration secret keys are supported for generating agency access tokens

We have outlined the process that you need to follow to use this endpoint below:

1. You receive an integration secret key from your Root representative.
2. You use that integration secret key to generate agency access tokens.
3. You use that agency access token to access our other APIs.

This provides scoped access to the intended agency, and it ensures that any API actions are attributed to the appropriate agency and agent.

Generating an agency access token

Once you have your integration secret key, you can create tokens using our "Create token" endpoint.

Body Parameters (all optional):

You may use different combinations of these parameters, and you will have the most success using only one parameter for your particular use-case.

For example, you may wish to only provide the agent_email to identify an agent; however, you may instead provide the agent_id, if that's the data to which you have access.

Note: You will receive a 404 No parameters provided response if no parameters are provided to the API call, and you will receive a 422 multiple token references response if we are unable to determine exactly one agency for which we should provide access.

Example Request:

{  
  "agentEmail": "[email protected]"  
}  

Example Response:

{  
  "bearerToken": "fzJ0hXBiOiJKV2QiLCJhbGciOiJFUzI1NiJ9.eyJyZWZi1iI2KEtjZWdkWTVHYDtKMVVISjlTV3BGcFkiLCJqYXQiOjE3NDc0MjA4MzgsImV4cCI6NTc0NzUxMDczOCwiYWdlbnRJZCI6IjJlZDQ3OTQ1LWQxYjMtNDIxNS04ZmNlLWYzNjExMTFhYTJlYyK8.CVjlNNHrTGH1t_4b-lGxfSBbTqgk7tv-HvAnBZsCdC8rlk0BwnqT-puTBNGFPdJ2vx9I7SElqpWgTmjDJrNxfh",  
  "tokenPayload": {  
    "ref": "7XKcegdY6GakJ1UHJ9SWpFkC",  
    "iat": 1711234567,   
    "exp": 1711839367,    
    "agentId": "677c6943-52d8-4fdb-a4b0-1ea4e16d96f9"
  }  
}

If you successfully generated an agency access token (referred to as "bearerToken" in the response), then you simply need to include it as the Authorization header in your subsequent API requests!

Managing Multiple Token References

If we are unable to determine exactly one agency from the body parameters provided to our "Create token" endpoint, we will return a list of token references like this:

{
  "tokenReferences": [
    {
      "agencyName": "Some Agency",
      "partnerAgencyId": "",
      "partnerAgencyName": "Some Partner",
      "tokenReference": "7XKcegdY6GakJ1UHJ9SWpFkC"
    }
  ]
}

This response will help you identify the agency for which you wish to provide access. Then, you can call the same endpoint again; however, this time, you should provide (in the body parameters) the partner_agency_id or token_reference for the intended agency from the prior response.

Expiry and Token Management

The agency access tokens are JWTs which include iat (issued at) and exp (expiration) timestamps. When the agency access token expires or is manually revoked, it become unusable. If you attempt to use an inactive agency access token for any API endpoint, you will receive a 401 Unauthorized response.

If your agency access token has expired or been manually revoked, you can simply call our "Create token" endpoint again to generate a fresh one!

Tip: Monitor token expiry proactively if you’re using long-running services.

We don’t currently support refreshing existing tokens which have expired or been manually revoked. Each token is short-lived and revokable by design.

How to mimic a "refresh" for an agency access token

To essentially "refresh" an agency access token, you can submit the same body parameters to our "Create token" endpoint again, which should result in a similar agency access token as generated previously.

If, for any reason, you wish to "refresh" an agency access token but don't know the exact body parameters you used to generate it, you can generate a new similar agency token through the following steps:

1. Decode the agency access token payload using a JWT decoder (example).
   1. Ignore the signature and expiration, since we only care about the payload.
2. Pull off the ref and agentId values from the decoded payload.
3. Call our "Create token" endpoint with the following body parameters:\
   
   JSON

   {  
     "tokenReference": "<ref>",
     "agentId": "<agentId>"
   } 

   
   

Security Incident Response

If you suspect that an agency access token or your integration secret key has been exposed, please reach out to your Root representative immediately.

We support two levels of response, depending on the nature of exposure:

Option 1: Revoke all issued agency access tokens

If only individual agency access tokens were exposed, and your integration secret key is still secure, your Root representative will revoke all currently active agency access tokens.

Once revoked:

• All agency access tokens generated for that particular agency stop working immediately.
• You will still be able to generate new agency access tokens with your integration secret key, using our "Create token" endpoint.

This is the fastest recovery path if you're confident that the integration secret key was not exposed.

Option 2: Revoke all agency access tokens and rotate the integration secret key

If your integration secret key was exposed, or you are unsure, your Root representative will revoke all active agency access tokens and your integration secret key.

In this case:

• All agency access tokens generated for all agencies with access to your integration stop working immediately.
• Your current integration secret key will also stop working immediately.
• We will generate a new integration secret key for your integration.
• You will be able to generate new agency access tokens with your new integration secret key, using our "Create token" endpoint.

This is a safest recovery path, since it ensures that you have a fresh integration secret key.

Legacy API Key

A legacy API key is an auth token which is scoped to a particular agency with access to your integration. This was traditionally the type of API key we would issue for partners, but this became cumbersome to manage for certain partners which had to keep track of many agencies. Therefore, we have deprecated this type of API key in favor of integration secret keys (see above for more details on that auth token type).

This type of auth token will always begin with: sk_test_ or sk_live_.

Security Incident Response

If you suspect that your legacy API key has been exposed, please reach out to your Root representative immediately.

If your legacy API key was exposed, or you are unsure, your Root representative will revoke that key's access to Root's APIs.

In this case:

• Your current legacy API key will stop working immediately.
• We will bias toward generating a new integration secret key for your integration, or (if you are unable to support using an integration secret key) we will generate a new legacy API key for you.