NationBuilder is building a v2 API that will only support our v2 access tokens. Unlike our v1 access tokens, v2 access tokens expire after 24 hours and can only be granted via the OAuth authorization code flow.

In the future, we will deprecate our v1 API and all client applications will be required to use v2 access tokens for NationBuilder's API. We plan to remove support for v1 tokens one year after the v2 API is released. A date will be added here once the v2 API is available.

In the meantime, we are allowing developers to migrate their applications to v2 access tokens on a per application basis if you'd like to get ahead of the curve. v2 access tokens are compatible with our v1 API. Please contact NationBuilder Support if you want to receive access to migrate to v2.

Requirements for V2 Applications

Your application must use the authorization code OAuth flow and implement a refresh token flow before you can migrate to v2 access tokens. If not, your application will encounter 401s because v2 access tokens expire after 24 hours. See the API Authentication Quickstart Guide for instructions on implementing the authorization code and refresh flows.

Migration Path for V2 Access Tokens

This migration path allows you to exchange v1 tokens for v2 tokens via the refresh flow. NationBuilder admins will not have to re-auth their nations for your application, and there should be no disruption to your service.

Please implement the following very carefully.

1. Ensure that your application is using the OAuth authorization code flow with a refresh flow.

   If you have implemented a refresh flow, you should have also implemented an association between an access token and its refresh token.

2. Store the access token value as the refresh token value for each of the valid v1 access tokens in your system. In other words, make each access token's refresh token associated with it the same as the access token.

   For example, if your system has three access tokens:

     {
       "access_token": "asdfasdfasdf",
       "refresh_token": null 
     },
     {
       "access_token": "qwerqwerqwer",
       "refresh_token": null
     },
     {
       "access_token": "yuioyuioyuio",
       "refresh_token": null
     }
   

   You should update them to:

     {
       "access_token": "asdfasdfasdf",
       "refresh_token": "asdfasdfasdf" 
     },
     {
       "access_token": "qwerqwerqwer",
       "refresh_token": "qwerqwerqwer"
     },
     {
       "access_token": "yuioyuioyuio",
       "refresh_token": "yuioyuioyuio"
     }
   

3. If your application is using the OAuth authorization code flow, a refresh flow, and you've updated your access tokens' refresh tokens, you are ready to convert to v2 access tokens. Contact NationBuilder support to get your nation access to the v2 migration switch if you do not have it already.

4. Navigate to Settings -> Developer -> Your apps. Edit the application you are converting to v2 access tokens.

5. You will see the "Convert to v2 access tokens" section at the top of the page. It is critical that you do not flip this switch until after you have completed all of the steps above. When you're sure you're ready, click it and your application will be updated immediately.

That's it! All your existing v1 access tokens will be set to expire in 24 hours from the time they were created. That means any access tokens created more than 24 hours ago will expire immediately. Your application should go through the refresh token flow with these tokens when they expire. The refresh_token values you set in step #2 above will be valid to use as refresh tokens to get new v2 access tokens in return. All of your existing v1 tokens can be exchanged for v2 tokens this way. All future tokens issued to your application will be v2 tokens.

Note: The new v2 tokens you receive will not have the same access token and refresh token value. Setting the refresh tokens is a one-time migration update; you should not manually change your access or refresh tokens again.