Document joining an all-access project (POST /buckets/:id/admissions.json) - #437
Conversation
There was a problem hiding this comment.
Pull request overview
Documents how users can join eligible all-access projects through the admissions endpoint.
Changes:
- Adds the endpoint to the people API index.
- Documents success, authorization failures, discovery limitations, and cURL usage.
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.
A person who isn't admissible gets 404, not 403. Someone who already has access is redirected to the project. The 403 "seek admission" response comes from reading inside an unjoined all-access project, and carries the URL to join. Also lists which admissions policy admits whom, and fixes the link to Get all projects.
617f4ac to
678baf0
Compare
There was a problem hiding this comment.
🟡 Changes recommended
The JSON example needs the required response heading and matching route markers before approval.
Get a fresh assessment by requesting another Copilot review.
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Balanced
The policy is checked before access, so someone already on a project the policy doesn't admit them to gets 404, not a redirect. admission_url has no .json, so POST it as JSON to get 201. Writes inside a joinable all-access project join implicitly. Owners, not the owner. Agent tokens get 403. projects.md's admissions values now say who can join, and employee is the narrower one.
…t fail later Bookmark writes don't go through the implicit join, so it's most writes, and a write that joins and is then refused keeps the join. The 403 example now names its route and carries the response heading and markers.
There was a problem hiding this comment.
🟡 Changes recommended
The discovery workflow is incomplete, and the PR description contradicts the documented eligibility and status behavior.
Get a fresh assessment by requesting another Copilot review.
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 2
- Review effort level: Balanced
GET /projects.json can't list it, so point at the project's web URL or at someone who can see the project.
|
🤖 Rebased at Jorge's request onto the #446 sync, corrected to match bc3's admissions controller, and merged. Thanks, @jeissonneira. The same text is in bc3's source in basecamp/bc3#13389. |
Summary
sections/people.mddocumentingPOST /buckets/:id/admissions.json— the current person joins a project whoseadmissionspolicy allows it (all-access:teamoremployee)201 Createdempty-body success, the404 Not Foundfor people the project's policy doesn't admit (such as clients, or non-owners on invite-only projects), the403 Forbidden/ "You must first seek admission" response from reading inside a project the person could join but hasn't, and whyGET /projects.jsoncan't surface a joinable project (it lists only projects you've already joined, so the ID has to come from the project's web URL or someone who can see it)Notes for maintainers
I ran into this building an agent against the API. The projects it needed were all-access, so it should have been able to reach them — but
GET /projects.jsonreturns only projects you've already joined, so those projects were simply invisible to it, and nothing in the docs says how to join one. The fix was manual every time: either I joined the project on the agent's behalf, or someone drove the web UI to do it.POST /buckets/:id/admissions.jsondoes exactly this, and it's been working well for us — the agent now admits itself to an all-access project instead of waiting on a person. Right now the docs coveradmissionsonly as a policy you set on a project (Update a project), never as something a person can act on, so this fills in the other half.The wording is a proposal — reshape it however fits. One process note: I don't have bc3 access, so this is a hand-edit against the mirror rather than
script/api/sync_to_bc3_apioutput. Happy for it to be treated as a content proposal fordoc/api/and overwritten by the next sync.Maintainer update
🤖 Rebased onto master at Jorge's request, after the full sync in #446. jeissonneira's commit and authorship are kept. Correction commits follow it, checked against bc3's
Buckets::AdmissionsController,Project::AdmissibleandBucketableAdmissions:404for people the policy doesn't admit,302for an admitted person who already has access, and the 403 prompt comes from reading inside an unjoined project.admission_urlbehaves, and that most writes join implicitly.admissionsvalues insections/projects.md.The docs also say
inviteprojects admit account owners. And the endpoint works with a user's OAuth token, while agent-principal tokens get403 Forbiddenfrom it.The identical text is also in bc3's
doc/apiin basecamp/bc3#13389, so the next sync keeps it.