Repository navigation
[SE-664] APIv3 endpoint for collaboration tokens for documents (behind feature flag) - #26279
Open
judithroth wants to merge 3 commits into
Open
judithroth wants to merge 3 commits into
judithroth wants to merge 3 commits into
Conversation
github-actions
Bot
added
the
ai: Collaborative 💻
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Anonymous callers with public-document access can receive collaboration tokens that cannot authenticate Hocuspocus's document requests.
1 open issue
What changed in this PR
Adds a feature-flagged APIv3 endpoint so mobile clients can obtain document collaboration tokens for Hocuspocus, while retaining the existing frontend refresh mechanism.
Changes:
- Adds token creation, response metadata, and document action links behind
documents_collaboration_token_api. - Supports optional previous-token validation and delayed revocation.
- Adds API documentation and tests for permissions, encryption, token replacement, and feature gating.
| File | Description |
|---|---|
| modules/documents/spec/support/shared/collaboration_token_endpoint.rb | Shared endpoint authorization and response tests. |
| modules/documents/spec/services/documents/oauth/token_with_metadata_service_spec.rb | Tests token creation, validation, revocation, and rollback. |
| modules/documents/spec/services/documents/oauth/ensure_application_service_spec.rb | Tests collaboration-token identification. |
| modules/documents/spec/services/documents/oauth/decrypt_token_service_spec.rb | Tests decryption and invalid-token handling. |
| modules/documents/spec/requests/api/v3/documents/collaboration_token_resource_spec.rb | Covers endpoint responses and token replacement. |
| modules/documents/spec/models/document_spec.rb | Tests collaboration availability. |
| modules/documents/spec/controllers/documents/refresh_tokens_controller_spec.rb | Tests rejection of non-collaborative documents. |
| modules/documents/spec/api/v3/utilities/path_helper_spec.rb | Tests the token endpoint path. |
| modules/documents/spec/api/v3/documents/document_representer_rendering_spec.rb | Tests action-link visibility and caching. |
| modules/documents/lib/open_project/documents/engine.rb | Registers the feature flag and API path. |
| modules/documents/lib/api/v3/documents/documents_api.rb | Mounts the endpoint and memoizes document lookup. |
| modules/documents/lib/api/v3/documents/document_representer.rb | Adds the conditional token action link. |
| modules/documents/lib/api/v3/documents/collaboration_token_representer.rb | Defines token response fields and links. |
| modules/documents/lib/api/v3/documents/collaboration_token_api.rb | Implements guarded token creation and error responses. |
| modules/documents/config/locales/en.yml | Adds token-related error messages. |
| modules/documents/app/services/documents/oauth/token_with_metadata_service.rb | Adds preconditions and transactional token replacement. |
| modules/documents/app/services/documents/oauth/token_encryptor.rb | Extracts shared cipher configuration. |
| modules/documents/app/services/documents/oauth/ensure_application_service.rb | Identifies collaboration application tokens. |
| modules/documents/app/services/documents/oauth/encrypt_token_service.rb | Uses shared encryption configuration. |
| modules/documents/app/services/documents/oauth/decrypt_token_service.rb | Adds collaboration-token decryption. |
| modules/documents/app/models/document.rb | Centralizes collaboration availability checks. |
| modules/documents/app/controllers/documents/refresh_tokens_controller.rb | Updates token service arguments. |
| modules/documents/app/controllers/documents_controller.rb | Uses the shared availability check and updated service. |
| docs/api/apiv3/tags/documents.yml | Documents collaboration connection and refresh steps. |
| docs/api/apiv3/paths/document.yml | Adds token action links to response examples. |
| docs/api/apiv3/paths/document_collaboration_token.yml | Documents endpoint inputs, responses, and restrictions. |
| docs/api/apiv3/openapi-spec.yml | Registers the endpoint and response schema. |
| docs/api/apiv3/components/schemas/document_model.yml | Documents the conditional token action link. |
| docs/api/apiv3/components/schemas/collaboration_token_model.yml | Defines the collaboration-token response schema. |
Review effort: Balanced
judithroth
force-pushed
the
feature/se-664-api-token-gen-behind-feature-flag
branch
from
October 23, 2026 15:00
6b70314 to
e327ee2
Compare
https://community.openproject.org/wp/SE-664 - POST /api/v3/documents/:id/collaboration_token creates an encrypted token for the collaboration server (Hocuspocus). - An optional `token` revokes the previous token 30 seconds later; each token can be revoked only once (race-free). - Requests authenticated with a collaboration token (an OAuth token issued to the Documents OAuth application) are rejected with 403. - Includes the OpenAPI docs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
https://community.openproject.org/wp/SE-664 They can not connect anyway, so why give them tokens. Fixing the behaviour for anonymous users on instances that are public and have a public project with documents is out of scope of this PR though.
judithroth
force-pushed
the
feature/se-664-api-token-gen-behind-feature-flag
branch
from
October 23, 2026 15:11
e327ee2 to
eed5d55
Compare
judithroth
marked this pull request as ready for review
October 23, 2026 15:27
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ticket
https://community.openproject.org/wp/SE-664
What are you trying to accomplish?
Enable to get collaboration tokens for documents via the APIv3, so that e.g. the mobile app can get a token and connect to Hocuspocus. This is behind a feature flag for now, so the mobile team can test earlier. This is a spin-off of #25879 , which I would also like to finish to get rid of the feature flag, but likely takes a little more time.
What approach did you choose and why?
Add new APIv3 endpoint which generates a token, which can be used to connect to Hocuspocus for that document. Optionally, it allows to send the previous token with the request, so it can be revoked.
Out of scope (will be a separate PR)
AI involvement
Collaborative – AI generated a substantial part of the code; I reviewed and understand every line.
Merge checklist