Skip to main content

API Authentication Quick Start Guide

Preliminary: If you already have an account, just login to the control panel and continue below. To get an account, please apply to become a Certified Developer. You will be given a sandbox account.

If you want to begin testing the API from your own nation or are building an app for a single customer, you can use test tokens to get started immediately. In your nation's control panel, go to Settings > Developer > API token.

Developer tools are only available to NationBuilder certified developers or nations on an Enterprise or Network plan. If you are looking to connect an application that is not already one of our integrations, you can reach out to one of our certified developers or apply to be certified.

  1. Register the application

    Log into your nation, navigate to Settings > Developer > Register app. Register your application with a name and OAuth callback URL. After you register, make sure to record the Client ID and Client Secret codes provided here for future use.

  2. Ask a nation's administrator for access

    Next, the administrator of the nation who is attempting to authenticate your application with their nation needs to login to their nation. Practically, you will need a freeform text field where the nation admin can manually enter their nation slug. After this is complete you can take the slug the customer has provided and set the {slug} of the nation the customer must login to:

    Note: You can receive an access token to make requests on behalf of a person with permission level 'staffer', but that access token will not allow you to use the endpoints currently documented. In the future endpoints may be individually segregated into permission level necessary.


    Where the clientid and redirecturi are the values from your app's registration. Uid is the label for client_id used in the app's registration page. {slug} is the nation's slug.

    The user will be shown a form stating that your application has requested access to their nation. From here they can select ‘Authorize’ and complete authentication.

  3. Record the code that comes back

    If the nation's admin accepts your request, we will redirect him/her to your redirect_uri with a code parameter in its query string, so a request will come through like this:


    Record this code for the next step

  4. Exchange the code for an access token

    Exchange that code for an access token by issuing a request for one like this:


    A practical example is using the command line utility cURL like this:

    curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --data '{"grant_type":"authorization_code", "code":"{code}", "client_id":"{client_id}", "client_secret":"{client_secret}", "redirect_uri":"{redirect_uri}"}'

    This request will receive a response like this:

      "access_token": "a44bdfe7972f7a83f5dc485cd3a7c7d2d09b0c60828ed24657c0b61e186ed93a",
      "token_type": "bearer",

    Record the access token from the response you receive to this request

  5. Use the access token to get data

    With this access token you can make requests on the user's behalf. See our API endpoint documentation for full details, but as an example, this is the request you would use to get the first page of people in a nation:


    Note that the API speaks only in javascript object notation (JSON), and that 406 response code means that you need to include the Content-Type and Accept headers of your request to "application/json".

Please direct API-related questions to [email protected].