Sync API docs from bc3: Basecamp-served authorization document - #435
Conversation
There was a problem hiding this comment.
Pull request overview
Documents Basecamp’s authorization endpoint and its token-specific response fields.
Changes:
- Adds response and cURL examples.
- Documents
resource,scope, identity, expiration, and DPoP behavior.
Tip
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| **Note on authenticating users via OAuth**: We don't recommend using the OAuth API to authenticate users in third-party services (e.g. a "Login with Basecamp" button). We don't verify email addresses, so an attacker could gain access using email addresses they don't own. | ||
|
|
||
|
|
||
| Get authorization from Basecamp |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b462c21155
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Get authorization from Basecamp | ||
| ------------------------------- |
There was a problem hiding this comment.
When readers use the endpoint list at the top of this section for discovery or anchor navigation, the newly added endpoint is missing, so they cannot see or jump to #get-authorization-from-basecamp from that list. Add a matching bullet alongside the existing authorization link, as required by the section-file structure.
AGENTS.md reference: AGENTS.md:L38-L42
Useful? React with 👍 / 👎.
| prefix — for any token it accepts: a Basecamp-issued OAuth token or personal | ||
| access token, or a legacy Launchpad-issued token. It mirrors Launchpad's |
There was a problem hiding this comment.
For users choosing an authentication method, this newly documented support for personal access tokens directly conflicts with both this guide's opening statement that all requests use OAuth 2 and README.md's authentication section saying OAuth 2 is mandatory. Update the overview and main guide to describe when personal access tokens are supported; otherwise readers receive mutually exclusive instructions about a token type this endpoint explicitly accepts.
Useful? React with 👍 / 👎.
| - `identity` carries only `id`. The name and email fields are omitted: they | ||
| were never suitable for identifying users within Basecamp (see the note on | ||
| the Launchpad document above) — use the [Get person][people] endpoints. |
There was a problem hiding this comment.
When a client needs the authenticated user's name or email omitted from this document, the linked Get person endpoint requires a Basecamp person ID, while this paragraph explicitly says the returned identity ID is not suitable for identifying that person. Following the link therefore leaves the client without a usable ID and may lead it to request the wrong profile; point readers to GET /my/profile.json (Get my personal info), which resolves the current user without an ID.
Useful? React with 👍 / 👎.
Documents
GET https://3.basecampapi.com/authorization.json— the authorization document Basecamp serves itself (both token types, the RFC 8707resourceindicator, thescopepresence rule, identity-id-only shape, ISO 8601expires_at) — from basecamp/bc3#12646, now deployed.Synced from bc3
doc/api/byscript/api/sync_to_bc3_api— not a hand-edit.