# Authentication A guide on how to use and generate auth tokens to access Root's APIs 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 ``` 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](https://root-bind-api.readme.io/reference/createtoken), 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](https://root-bind-api.readme.io/reference/createtoken). # 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](https://root-bind-api.readme.io/reference/createtoken) 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](https://root-bind-api.readme.io/reference/createtoken). Body Parameters (all optional): | Field | Description | | --------------- | --------------------------------------------------------------------------------- | | agentEmail | The email of the agent you would like to attribute to quotes made with this token | | agentId | The ID of the agent you would like to attribute to quotes made with this token | | partnerAgencyId | The partner agency ID you want to authorize with this token | | tokenReference | The specific reference to a credential associated with a partner agency | 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: ```json { "agentEmail": "test.agent@joinroot.com" } ``` Example Response: ```json { "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](https://root-bind-api.readme.io/reference/createtoken), we will return a list of token references like this: ```json { "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](https://root-bind-api.readme.io/reference/createtoken) 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](https://root-bind-api.readme.io/reference/createtoken) 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](https://jwt.io/)). 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](https://root-bind-api.readme.io/reference/createtoken) with the following body parameters:\
```json { "tokenReference": "", "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](https://root-bind-api.readme.io/reference/createtoken). **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](https://root-bind-api.readme.io/reference/createtoken). **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.