Basecamp#
Basecamp is registered for OAuth-backed API sync. It connects a Basecamp account through Launchpad OAuth, pulls Basecamp to-dos into a reviewable import session, and imports Basecamp people/task actors into the same user-mapping flow.
| Capability | Method | Status |
|---|---|---|
CSV_IMPORT |
— | Not built |
SYNC |
Pull Basecamp to-dos from the Basecamp API | ✅ Built |
USER_IMPORT |
Import Basecamp people during sync | ✅ Built |
WEBHOOK |
— | Not built |
The endpoints below live under /api/v1/providers/basecamp/.... All routes
require an organization-scoped user token (see Authentication).
OAuth Install#
Basecamp does not use API keys. Configure a Basecamp OAuth app in the service environment, then have the frontend/operator start OAuth for the organization:
GET /api/v1/providers/basecamp/oauth/authorize?organization_id=<id>
POST /api/v1/providers/basecamp/oauth/callback?organization_id=<id>
GET /oauth/authorize returns an authorizationUrl and signed state. After
Basecamp redirects to the configured redirect URI with a code and the same
state, post both values to /oauth/callback. The callback exchanges the code,
discovers the first accessible Basecamp 5 (bc3) account from Launchpad, and
stores the OAuth token bundle encrypted at rest. Access and refresh tokens are
never returned by any endpoint. The relay's complete shared request shape and
state/callback-value security rules are documented under
Authentication.
Required service env vars:
BASECAMP_CLIENT_ID=<from Launchpad>
BASECAMP_CLIENT_SECRET=<from Launchpad>
BASECAMP_REDIRECT_URI=https://<frontend-host>/oauth/basecamp
BASECAMP_USER_AGENT="TeamBoost Integrations (integrations@example.com)"
Direct PUT /providers/basecamp/credentials upload is not supported for OAuth
tokens; use the OAuth install flow. GET /credentials reports configured status,
DELETE /credentials removes the stored bundle, and sync refreshes tokens before
use when they are close to expiry.
Importing From Basecamp#
POST /api/v1/providers/basecamp/imports/sync?organization_id=<id>
The adapter uses the stored OAuth token to:
- list visible active projects;
- skip projects whose To-dos dock item is disabled;
- list active to-do lists under each enabled To-dos set;
- import active pending to-dos and active completed to-dos;
- import visible account people plus task creators, assignees, and completion actors.
Archived/trashed projects, lists, and to-dos are not imported in this first Basecamp sync. Card Table cards are also deferred.
Projection Field Coverage#
| Basecamp source | TeamBoost draft field | Notes |
|---|---|---|
content / title |
title |
Error if shorter than 2 characters |
description |
description |
Preserved as Basecamp-provided text/HTML |
| completion flag | status |
pending active to-dos → NOT_STARTED; completed to-dos → COMPLETED |
| no native type | type |
Defaults to OTHER with a mapping note |
| no native priority | priority |
Defaults to UNKNOWN with a mapping note |
| first assignee person id/e-mail | ownerId |
Present-but-unmapped assignee is a blocking projectionError; additional assignees are preserved as context with a mapping note |
| creator person id/e-mail | creatorId |
Set when resolvable; otherwise left unset with a mapping note |
starts_on |
plannedStartDate |
Bare dates are treated as UTC dates |
due_on |
plannedEndDate |
Bare dates are treated as UTC dates |
| project name | projectTitle |
|
| to-do list title | taskGroupTitle |
|
| provider refs, URLs, project/list context, assignees, completion | descriptionJson |
Preserved for review/trace |
Basecamp person ids are the durable user-mapping key. E-mail is used only as a
hint when Basecamp returns an unredacted email_address; Basecamp may redact
e-mails for non-admin/non-owner OAuth users.
Not Built Yet#
- Basecamp CSV import.
- Basecamp Card Table card sync.
- Basecamp webhook verification and replay protection.