A Python script to make calls to the Basecamp 4 API via OAuth authentication.

basecamp.py

import datetime
import json
import os.path
import requests 

# TO DO: Enter Your BC Account ID
# Example: 999999999 from https://3.basecamp.com/999999999/
BC_ACCOUNT_ID = "<your-client-id>"

# Basecamp App Integration Information 
# TO DO: Register your integration at https://launchpad.37signals.com/integrations
# The values for the variables below will be given to you after registering your integration with Basecamp.
CLIENT_ID = "<your-client-secret>"
CLIENT_SECRET = "<your-client-secret>"
REDIRECT_URI = "<your-redirect-uri>" # Example: https://example.com/auth

# TO DO: Create an API User-Agent Header
# You are required to identify your integration (https://github.com/basecamp/bc3-api#identifying-your-application)
USER_AGENT = "<your-user-agent>" # Example: Fabian's Ingenious Integration (fabian@example.com)

# Basecamp OAuth Base URLs (Do NOT Change)
REQUEST_AUTH_URL = "https://launchpad.37signals.com/authorization/new"
TOKEN_URL = "https://launchpad.37signals.com/authorization/token"

# Basecamp Base API URL (Do NOT Change)
BC_BASE_API_URL = "https://3.basecampapi.com/" + BC_ACCOUNT_ID

# OAuth Token Details (Do NOT Change)
AUTH_CODE = ""
ACCESS_TOKEN = ""
EXPIRATION_DATE = ""
REFRESH_TOKEN = ""

# Return required header content for each API Call
def GetApiHeader():
  return {'Authorization': 'Bearer ' + ACCESS_TOKEN, 'Content-Type':'application/json; charset=utf-8', 'User-Agent': USER_AGENT}

# Function that will be used to make API calls after authentication is complete
# E.g. MakeAPICall("/projects.json") will make a request for all the projects on your account
#      Lear more about BC4 API: https://github.com/basecamp/bc3-api (Yes, that URL is correct.)
def MakeAPICall(request):
  api_results =  requests.get(BC_BASE_API_URL + request, headers=GetApiHeader(), verify=True)
  print(json.dumps(json.loads(api_results.text), indent=4))

# Writes OAuth token information to local file for "permanent" storage
def UpdateTokenFile():
  data = {}
  data['expires_at']    = EXPIRATION_DATE
  data['token']         = ACCESS_TOKEN
  data['auth_code']     = AUTH_CODE
  data['refresh_token'] = REFRESH_TOKEN

  with open('basecamp-token.json', 'w') as file:
    json.dump(data, file)

#####
# 1 #
#####

# Check if local JSON file containing Basecamp OAuth token information exists
if (os.path.exists("basecamp-token.json")):
  with open('basecamp-token.json', 'r') as file:
    data = json.load(file)

    # Set environmental variables
    AUTH_CODE = data['auth_code']
    ACCESS_TOKEN = data['token']
    EXPIRATION_DATE = data['expires_at']
    REFRESH_TOKEN = data['refresh_token']

#####
# 2 #
#####

# Check if an OAuth token needs to be generated
if (ACCESS_TOKEN == ""):
  # 1. Link to generate a new Verification Code 
  authorization_redirect_url = REQUEST_AUTH_URL + "?type=web_server&client_id=" + CLIENT_ID + "&redirect_uri=" + REDIRECT_URI
  
  print("Visit the following link: ")
  print(authorization_redirect_url)
  print()
  print("Accept Access to your Basecamp Account")
  print("After the page redirects, view the URL and get the value of the ?code parameter.")
  AUTH_CODE = input('Enter the Code: ')

  # 2. Get OAuth Token -- POST to the token_redirect_url to get the JSON response containing the OAuth token
  token_redirect_url = TOKEN_URL + "?type=web_server&client_id=" + CLIENT_ID + "&redirect_uri=" + REDIRECT_URI + "&client_secret=" + CLIENT_SECRET + "&code=" + AUTH_CODE
  access_token_response = requests.post(token_redirect_url)

  # Read in response as JSON and store OAuth token
  tokens = json.loads(access_token_response.text)
  ACCESS_TOKEN = tokens["access_token"]
  REFRESH_TOKEN = tokens['refresh_token']

  # 3. Get expiration date of token and store it
  api_auth_call_response = requests.get("https://launchpad.37signals.com/authorization.json", headers=GetApiHeader(), verify=True)
  EXPIRATION_DATE = json.loads(api_auth_call_response.text)['expires_at']
  
  # 4. Write token data to file
  UpdateTokenFile()

#####
# 3 #
#####

expirationUTCDate = datetime.datetime.strptime(EXPIRATION_DATE, "%Y-%m-%dT%H:%M:%S.%fZ") # UTC expiration date and time of OAuth token
currentUTCDate = datetime.datetime.utcnow() # Current system UTC date and time

if (expirationUTCDate <= currentUTCDate):
  print("TOKEN REFRESH IN PROGRESS")
  
  # 1. Get Refreshed OAuth Token -- POST to the token_refresh_url to get the JSON response containing the refreshed OAuth token
  token_refresh_url = TOKEN_URL + "?type=refresh&refresh_token=" + REFRESH_TOKEN + "&client_id=" + CLIENT_ID + "&redirect_uri=" + REDIRECT_URI + "&client_secret=" + CLIENT_SECRET
  access_token_refresh_response = requests.post(token_refresh_url)

  # Read in response as JSON and store OAuth token
  tokens = json.loads(access_token_refresh_response.text)
  ACCESS_TOKEN = tokens["access_token"]

  # 2. Get expiration date of refreshed token and store it
  api_auth_call_response = requests.get("https://launchpad.37signals.com/authorization.json", headers=GetApiHeader(), verify=True)
  EXPIRATION_DATE = json.loads(api_auth_call_response.text)['expires_at']
  
  # 3. Write refreshed token data to local file
  UpdateTokenFile()
  
  print("TOKEN REFRESHED")

#####
# 4 #
#####

# Use the MakeAPICall() function to call the BC4 API
MakeAPICall("/projects.json")

The below function will print all open and visible todo's for your authenticated Basecamp account. Open tasks will be grouped by project and then by the task list they are assigned within the project. The output will be in the following format:

Project 2:
	-Task List 1
		[ ] Task 1 to be Completed
	-Task List 2
	-Task List 3
Project 1:
	-Task List 1
		[ ] Task 1 to be Completed
	-Task List 2
	-Task List 3
	-Task List 4
		[ ] Task 1 to be Completed
		[ ] Task 2 to be Completed
		[ ] Task 3 to be Completed

The following GetAllOpenTodos() function can be added to the end of the script above. Calling this function will then print all open todos that are in visible To Do lists in the format described above.

# Get all open, visible ToDo(s) in a every project (separated by project and then by task list)
def GetAllOpenTodos():
  projects = requests.get(BC_BASE_API_URL + "/projects.json", headers=GetApiHeader(), verify=True).json()
  for project in projects:
    print(project["name"] + ":")

    for bucket in project["dock"]:
      if bucket["name"] == "todoset" and bucket["enabled"] == True:
        lists = requests.get(BC_BASE_API_URL + "/buckets/" + str(project["id"]) + "/todosets/" + str(bucket["id"]) + "/todolists.json", headers=GetApiHeader(), verify=True).json()

        for list in lists:
          print("\t-" + str(list["title"]))

          tasks = requests.get(BC_BASE_API_URL + "/buckets/" + str(project["id"]) + "/todolists/" + str(list["id"]) + "/todos.json", headers=GetApiHeader(), verify=True).json() 
          
          for task in tasks:
            print("\t\t[ ] " + task["title"])