Auth

The Basecamp API follows draft 5 of the oAuth 2 spec

In short, this is how it works:

  • Ask for access
  • A user authenticates with their Basecamp account
  • Get a verification code.
  • Trade that code in for an access token.
  • Start performing authenticated requests with said token.

Basic usage

>>> import basecamp.api
>>> auth = basecamp.api.Auth(client_url, client_secret, redirect_url)
>>> launchpad_url = auth.launchpad_url

Redirect to the launchpad_url in your application after the user authenticates, they are redirected back to the redirect_url location, and a code GET variable will be present to exchange for a token.

>>> import basecamp.api
>>> auth = basecamp.api.Auth(client_url, client_secret, redirect_url)
>>> token = auth.get_token()

Examples

Here’s a basic example of how this could work in a Flask application.

import basecamp.api
from secrets import client_id, client_secret, return_url
from flask import Flask, redirect, request

app = Flask(__name__)

@app.route('/basecamp-login/')
def basecamp_login():
    '''
    Redirect user to basecamp to authenticate.
    '''
    auth = basecamp.api.Auth(client_id, client_secret, return_url)

    return redirect(auth.launchpad_url)

@app.route('/auth-return/')
def auth_return():
    '''
    Get the code and exchange it for an access_token
    '''
    code = request.args.get('code')

    auth = basecamp.api.Auth(client_id, client_secret, return_url)

    token = auth.get_token(code)

    # do things now that you have a token.
class basecamp.auth.Auth(client_id, client_secret, redirect_uri)

Class to perform basic auth operations

get_accounts(access_token, account_type='bcx')

Get 37signals accounts for the authenticated user.

Parameters:
  • access_token – access token obtained from get_token()
  • account_type – type of basecamp account to return. Return only Basecamp Next accounts by default.
Return type:

dictionary
get_identity(access_token)

Get the users identity.

As per the docs:

An identity is NOT used for determining who this user is within a specific application. The id field should NOT be used for submitting data within any application’s API. This field can be used to get a user’s name and email address quickly, and the id field could be used for caching on a cross-application basis if needed.
Parameters:access_token – access token obtained from get_token()
Return type:dictionary
get_token(code)

This function requests the auth token from basecamp after oAuth has happened and the user has approved the application.

Parameters:code – the code returned from launchpad_url()
Return type:dictionary

The response should contain the following:

  • expires_in (seconds)
  • access_token (a really long string, you’ll need this later)
  • refresh_token (another really long string. Hang onto this as well.)
launchpad_url

Get the URL to send your application to.

For instance, in a Django app, one could do something like:

>>> import basecamp.api
>>> from django import http
>>> auth = basecamp.api.Auth(client_id, client_secret, redirect_uri)
>>> http.HttpResponseRedirect(auth.get_launchpad_url)