✨ Feature Request: API Access to Retrieve Private Markdown Documents Securely

[ThomasSanson]

Title: Feature Request: Simple Token-Based API Access for Private Documents (Initial Phase)

Feature Request

Is your feature request related to a problem or unsupported use case? Please describe.
Currently, users cannot programmatically retrieve their private documents from Docs without manual intervention. This prevents automation of workflows like backups, content integration, or syncing with external tools while keeping documents private.

Describe the solution you'd like
A minimal, secure API to retrieve documents privately, inspired by Grist’s simplicity:

1. Token Generation:

   • Users can generate a personal API token in their account settings (e.g., under "API Tokens" or "Integrations").
   • Example UI: A button to "Generate new token" with a clear warning about token security.

2. Endpoints:

   • List Documents:

     GET /api/documents  

     Returns a simple JSON list of documents the user has access to, with metadata (e.g., id, title, last_modified).

   • Get Document Content:

     GET /api/documents/{document_id}  

     Returns the document’s content in Markdown (or raw JSON/HTML if Markdown conversion is complex).

3. Authentication:

   • Token sent via Authorization: Bearer {token} header.
   • Tokens inherit the user’s permissions (e.g., only documents they can view are accessible).

Drawbacks:

• Minimal filtering/pagination for /api/documents initially (can be improved later).
• No support for bulk exports or formats like PDF in this phase.

Describe alternatives you've considered

• Manual UI Exports: Not scalable for automation.
• Web Scraping: Fragile and insecure.
• Complex API Design: Overkill for initial use cases. A minimal MVP aligns better with user needs.

Discovery, Documentation, Adoption, Migration Strategy

• Discovery: Users find the token generator in their profile/account settings.

• Documentation Example:

  ### Retrieve Documents via API (Beta)  
  1. **Generate a token**:  
     Go to **Account Settings → API Tokens → Generate Token**.  
  
  2. **List your documents**:  
     ```bash  
     curl -H "Authorization: Bearer YOUR_TOKEN" https://{instance}/api/documents  

  3. Get a document:

     curl -H "Authorization: Bearer YOUR_TOKEN" https://{instance}/api/documents/DOCUMENT_ID  

• Adoption: Announce this as a beta feature for developers/automation enthusiasts.

• Security Note: Advise users to store tokens securely and rotate them periodically.

Do you want to work on it through a Pull Request?
Yes, I’d like to collaborate on this after aligning with maintainers on:

• Token storage/management implementation (e.g., Django REST Framework Token).
• Preferred response format (Markdown vs. existing Prosemirror/BlockNote JSON).

[ThomasSanson]

Feature: Secure API Access to Private Markdown Documents

  As a registered user
  I want to securely access my private Markdown documents via an API
  So that I can automate tasks like backups and integrations while maintaining document privacy

  Scenario: Generate a personal API token
    Given I am logged into my account
    When I navigate to the "API Tokens" section in my account settings
    And I click on the "Generate New Token" button
    Then I should see a new API token displayed
    And I should be able to copy the token for future use

  Scenario: Retrieve a list of private documents using the API token
    Given I have a valid API token
    When I send a GET request to the "/api/documents" endpoint with my API token
    Then I should receive a 200 OK response
    And the response should contain a JSON array of my private documents with their metadata

  Scenario: Access a specific private Markdown document using the API token
    Given I have a valid API token
    And I know the ID of a specific private document
    When I send a GET request to the "/api/documents/{id}" endpoint with my API token
    Then I should receive a 200 OK response
    And the response should contain the Markdown content of the specified document

  Scenario: Attempt to access documents with an invalid or expired API token
    Given I have an invalid or expired API token
    When I send a GET request to the "/api/documents" endpoint with the invalid token
    Then I should receive a 401 Unauthorized response
    And the response should indicate that the API token is invalid or expired

  Scenario: Revoke an existing API token
    Given I am logged into my account
    And I have previously generated API tokens
    When I navigate to the "API Tokens" section in my account settings
    And I click on the "Revoke" button next to a specific token
    Then the token should be invalidated
    And any future requests using that token should receive a 401 Unauthorized response

[virgile-dev]

Thanks @ThomasSanson for the issue !
Guys what's your take on this @arnaud-robin @lunika ?

[lunika]

Hi,
We are working on an other implementation to access docs externally. The idea is to use oidc to implement a resource server (https://github.com/suitenumerique/django-lasuite/tree/main/src/lasuite/oidc_resource_server). So it's not what you want but if you are using an app using the same OIDC provider, you can use this implementation (but still not released)

[ThomasSanson]

Thank you for your response, and for highlighting the ongoing work around OIDC-based external access.

I fully understand that your current implementation is exploring a different authentication flow. Nonetheless, my initial suggestion aimed to address simpler automation scenarios that do not necessarily involve federated identity or full application integration — for example, scripting periodic exports or syncing documents with third-party tools in a personal context.

Should there be any opportunity to explore a dual-track approach — supporting both federated OIDC for secure application-level access and a lightweight token-based API for user-level automation — I would be very keen to contribute to the discussion or help prototype such a feature.

Please do let me know if this is something worth pursuing further in parallel.

Warm regards,
Thomas Sanson

[virgile-dev]

As we're preping for the https://github.com/suitenumerique/hackdays2025, we'd like to work on the API so people can play around a hack cool things around Docs.
We discussed this w/ @arnaud-robin and here are the thing we'd like to be able to do with a Docs API
Who can use the API, all registered Docs users -> To perform a request, one must be authenticated.
P1

• Create a document: with title, content,
• Define rights: set link permissions and members.
• Read a document: retrieve a document content and metadata (link setting, members and permissions)

P2

• **List documents**: retrieve the documents the user has access to
• Update a document: modify title, content, metadata.
• Upload images/files: upload file to the S3 with the right permissions and insert into document content.

P3

• **Delete member**: from a document
• **Delete document**
• • **Relocate document**: move a document into a document or a sub-page

The endpoints should be accessible via url that can contain parameters ex: docs.numerique.gouv.fr/new?title="Awesome"&members="virgile@example.org,owner; arnaud@example.org, editor"

Later, for more advanced use cases and more secure usage a ressource server implementation like @lunika mentioned will be necessary.

[virgile-dev]

Discussed again with the team, we're took a crack at the ressource server implementation.
We'll provide an example for Keycloak.
See : #927

[ThomasSanson]

Hi @virgile-dev,

Top work on aligning this with the Hackdays initiative!

To clarify, does P1 essentially entail a basic CRUD API (Create, Read, Update, Delete) for documents, focusing on core operations such as document creation, permission management, and content retrieval ?

Either way, thank you for outlining the priorities so clearly. Please don’t hesitate to loop me in if there’s scope for collaboration—I’d be happy to assist with prototyping, testing, or refining the implementation.

Best regards,
Thomas Sanson

[virgile-dev]

Hey @ThomasSanson
What I said here is a bit obsolete.
#682 (comment)
The ressource server will expose the existing endpoints the docs API has. It can already do pretty much all things mentionned above.
You can find the api documentation /api/v1.0/swagger when running docs locally.

[ThomasSanson]

Ah yes, my apologies — I hadn't quite grasped the nuance.

All right then, excellent. May I close this issue?

Nonetheless, with regard to the OIDC component, my offer of assistance still stands. 😇