diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index b9551dcb..dc8fbdc0 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -64,5 +64,6 @@ jobs: pages-base-url: libresign.github.io/site-preview deploy-repository: LibreSign/site-preview preview-branch: gh-pages - wait-for-pages-deployment: true + # Another PR can supersede this Pages build on the shared repository. + wait-for-pages-deployment: false token: ${{ secrets.PREVIEW_TOKEN }} diff --git a/source/_posts/api-documentation.md b/source/_posts/api-documentation.md index 22cc9013..42c7d6d1 100644 --- a/source/_posts/api-documentation.md +++ b/source/_posts/api-documentation.md @@ -3,27 +3,30 @@ extends: _layouts.post title: LibreSign API Guide author: Vitor Mattos date: 2024-10-10 -description: Provides a practical guide on how to use the LibreSign API, including querying endpoints and understanding usage flows by observing requests in the application. +updated: 2026-11-10 +description: Use LibreSign's versioned OpenAPI contracts, official integration guides, and examples to connect external systems securely. categories: [features] icon: dashboard-square-1 --- -# LibreSign API: Endpoints and usage flows +# LibreSign API: Integrating with other systems -## API Endpoints +*Updated on November 10, 2026. Originally published on October 10, 2024.* -To find out which endpoints are available in the LibreSign API, follow these steps: +LibreSign is free and open-source software for electronic signatures on Nextcloud. Its REST API, based on Nextcloud's OCS protocol, lets an external system request signatures, track progress, and validate documents. An existing application can keep its own interface and workflows while its backend communicates with LibreSign. The API is included in the software; you do not need to purchase separate API access. Hosting, integration services, and support are optional. -1. **Install the OCS API Viewer App**: Start by installing the [OCS API Viewer](https://apps.nextcloud.com/apps/ocs_api_viewer) in your Nextcloud environment. -2. **Access the API Documentation**: In the Nextcloud menu, locate the OCS app. Here, you will find the documentation for the LibreSign API, as well as other Nextcloud APIs. +## Official integration documentation -## Understanding the LibreSign API usage flows +Start at the [official LibreSign documentation](https://docs.libresign.coop/). Choose the LibreSign release installed on your Nextcloud server, then open **Developer manual and API**. You will find integration guides, practical examples, the interactive OpenAPI reference, and its downloadable JSON contract. The guides cover signature requests, invitations, status checks, and authorized retrieval of signed documents. -To understand how to perform specific operations, such as requesting a signature, you can use the LibreSign application itself as a reference. Here’s how to do it: +Use the documentation for your installed release: available features and request fields can change over time. The development documentation may describe functionality not yet included in a stable release. -1. **Open Developer Tools**: Press the F12 key in your browser to access the developer tools. -2. **Go to the Network Tab**: Navigate to the "Network" tab to monitor the API requests. -3. **Filter the requests**: Use the filter to show only the requests related to LibreSign by typing "libresign." -4. **Perform actions in LibreSign**: Execute the desired actions in the LibreSign application. Observe the requests sent to the API at each step and analyze how they are structured. +## Authentication and integration with external systems -By following these steps, you will be able to query the available endpoints of the LibreSign API and understand the usage flows by monitoring the requests made by the application. This will help you integrate and use the API in your projects. +For a server-to-server integration, use HTTPS and an authorized Nextcloud account with a **revocable App Password**. OCS requests normally use HTTP Basic authentication and the `OCS-APIRequest: true` header. Keep credentials on your backend, never in client-side code. Bearer tokens depend on the authentication configuration of your Nextcloud instance; signing in to another application does not automatically grant API access. + +Your backend can create signature requests and track their status through documented endpoints. Depending on the settings enabled in LibreSign, recipients can sign with their Nextcloud accounts or through individual invitations without creating a Nextcloud account. An integration account must not be used to impersonate signers. + +## Browser inspection is a diagnostic tool + +The browser's Network tab (F12) and the [OCS API Viewer](https://apps.nextcloud.com/apps/ocs_api_viewer) can help investigate requests and responses on a specific installation. They are complementary troubleshooting tools, **not a replacement for the official OpenAPI contract**: browser calls can depend on session cookies or interface-specific behavior. Use the versioned guides and examples first, and avoid exposing credentials, signing links, or document contents when debugging.