API Usage

LibreSign exposes endpoints via REST and OCS (Open Collaboration Services).

By default, all requests require authentication (Basic Auth, App Password, OIDC, or session cookies) and return JSON responses.

Base URLs

OCS: https://cloud.example.com/ocs/v2.php/apps/libresign/api/v1/

Versioning: breaking changes result in a new major version (e.g., v2).

Authentication

Supported methods:

Basic Auth (App Password or Username/Password)
OIDC Access Token (Authorization: Bearer <ACCESS_TOKEN>)
Session cookies (for non-OCS endpoints, may require CSRF token)

Note

Prefer using an App Password for Basic Auth. For OIDC, use Access Tokens.

Note

Use an application password instead of your regular password. Besides improved security, this also improves performance.

To configure one:

log into the Nextcloud Web interface
click on your avatar,
select Personal settings, then Security.
At the bottom of the page you can create an app password, which can also be revoked later without changing your main password.

Basic Auth (App Password)

curl -sS -u "username:app-password" \
  -H "Accept: application/json" \
  -H "OCS-APIRequest: true" \
  "https://cloud.example.com/ocs/v2.php/apps/libresign/api/v1/..."

OIDC (Access Token)

Clients

Requests with a body (POST, PUT, PATCH) must include Content-Type: application/json.

CURL

All OCS requests can be tested with curl by specifying the request method (GET, POST, PATCH, etc.) and the required headers.

Example:

curl --request POST \
    --url http://cloud.example.com/apps/libresign/api/v1/request-signature \
    --header 'Authorization: Basic <base64-credentials>' \
    --header 'Content-Type: application/json' \
    --data '{
        "file": {
            "url": "https://example.com/test.pdf"
        },
        "status": 0,
        "name": "Contract",
        "users": [
            {
                "email": "a@b.c"
                "displayName": "User Name"
            }
        ]
    }'