REST API Reference

REST API Reference (FR-016)

This document provides complete technical specifications for the graphsign.ink REST API (/api/v1).

---

🌐 Base URL & Protocol

• Local Development: http://localhost:8787/api/v1
• Production: https://api.graphsign.ink/api/v1
• Transport: HTTPS required in production environments.
• Data Format: application/json (UTF-8).

---

🔑 Authentication & Headers

Authenticated endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <jwt-access-token>
Content-Type: application/json

---

📦 Standard Response Envelopes

Success Response Envelope

{
  "success": true,
  "data": { ... }
}

Error Response Envelope

{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested agreement was not found."
  }
}

---

📑 Complete Endpoint Catalog

1. Authentication (/api/v1/auth)

Method	Endpoint	Description	Auth
POST	/auth/register	Create new user account	No
POST	/auth/verify-email	Verify user email address with token	No
POST	/auth/resend-verification	Request fresh email verification token	No
POST	/auth/login	Sign in and receive JWT token	No
POST	/auth/login/mfa	Complete TOTP two-step login challenge	No
POST	/auth/logout	Invalidate current session and revoke token	Yes
POST	/auth/forgot-password	Request password reset link	No
POST	/auth/reset-password	Set new password using reset token	No
PUT	/auth/profile	Update user profile name and timezone	Yes
POST	/auth/profile/verify-email-change	Verify and apply new primary email address	Yes
POST	/auth/mfa/setup	Generate TOTP QR code and secret	Yes
POST	/auth/mfa/verify-setup	Enable TOTP MFA and receive backup codes	Yes
POST	/auth/mfa/disable	Disable TOTP MFA (requires password confirmation)	Yes
PUT	/auth/session-settings	Update organisation inactivity timeout	Yes (Admin)

2. Organizations & Teams (/api/v1/organisations)

Method	Endpoint	Description	Permission
POST	/organisations	Create new organization	Authenticated
GET	/organisations/me	Get organization profile, subscription, and storage usage	org:settings
PATCH	/organisations/me	Update organization branding and settings	org:manage
DELETE	/organisations/me	Soft-delete organization	org:manage (Owner)
POST	/organisations/teams	Create functional team	org:manage
GET	/organisations/teams	List organization teams	org:settings
POST	/organisations/domains	Register custom domain for DNS verification	org:manage
GET	/organisations/domains	List custom domains and DNS record status	org:settings

3. Agreements & Documents (/api/v1/agreements)

Method	Endpoint	Description	Permission
GET	/agreements	List agreements (supports status, isArchived, search)	documents:read
POST	/agreements/upload	Upload PDF/DOCX agreement binary	documents:write
POST	/agreements/scratch	Create agreement from scratch Markdown	documents:write
GET	/agreements/:id	Retrieve agreement metadata and status	documents:read
PUT	/agreements/:id/draft	Update draft title or Markdown content	documents:write
POST	/agreements/:id/activate	Promote draft to active state (0.x $\rightarrow$ 1.0)	documents:write
POST	/agreements/:id/clone	Clone agreement into a new draft	documents:write
POST	/agreements/:id/archive	Archive or unarchive agreement	documents:write
GET	/agreements/:id/file	Stream document content or PDF binary	documents:read
GET	/agreements/:id/history	Get change history timeline	documents:read
PATCH	/agreements/:id/tags	Update metadata tags	documents:write

4. Visual Fields & Recipient Placement (/api/v1/agreements/:id/fields)

Method	Endpoint	Description	Permission
GET	/agreements/:id/fields	Retrieve placed fields and recipient envelope settings	documents:read
PUT	/agreements/:id/fields	Save field positions, validations, and recipient mappings	documents:write

5. Workflow State Machine (/api/v1/agreements/:id/review & /send)

Method	Endpoint	Description	Permission
POST	/agreements/:id/review/submit	Submit draft for internal review	documents:write
POST	/agreements/:id/review/approve	Approve document	documents:write
POST	/agreements/:id/review/reject	Reject document with feedback notes	documents:write
POST	/agreements/:id/send	Send agreement for signature (Sequential or Parallel)	documents:write
POST	/agreements/:id/cancel	Void/cancel active envelope	documents:write
POST	/agreements/cron/check-expired	Background job to auto-expire past deadlines	Cron / Admin

6. Public Signer Portal (/api/v1/sign)

Method	Endpoint	Description	Auth
GET	/sign/:token	Resolve signer session and view assigned fields	Public Token
POST	/sign/:token/consent	Record electronic ERSD consent	Public Token
POST	/sign/:token/view	Record recipient viewed beacon	Public Token
POST	/sign/:token/otp/send	Dispatch one-time passcode for guest signer	Public Token
POST	/sign/:token/otp/verify	Validate guest signer OTP code	Public Token
POST	/sign/:token/complete	Submit electronic signature and field values	Public Token
POST	/sign/:token/decline	Decline signing request with feedback	Public Token
GET	/sign/:token/file	Stream PDF or Markdown document binary	Public Token
GET	/sign/:token/download	Download completed document with PAdES seal	Public Token

7. Templates (/api/v1/templates)

Method	Endpoint	Description	Permission
GET	/templates	List organization templates	templates:read
POST	/templates	Create new template	templates:manage
GET	/templates/:id	Get template details & fields	templates:read
PUT	/templates/:id	Update template content	templates:manage
DELETE	/templates/:id	Archive template	templates:manage
POST	/templates/:id/publish	Publish template for organization use	templates:manage (Admin)
POST	/templates/:id/clone	Clone template	templates:manage

8. Search & Filter Presets (/api/v1/search)

Method	Endpoint	Description	Permission
GET	/search/agreements	Search agreements by keywords, status, tags, and dates	documents:read
GET	/search/templates	Search template library	templates:read
GET	/search	Unified global search across agreements, templates, recipients	documents:read
GET	/search/presets	Retrieve saved search and filter presets	documents:read
POST	/search/presets	Save a custom filter preset	documents:write
DELETE	/search/presets/:id	Delete a saved filter preset	documents:write
PATCH	/search/presets/:id/default	Set preset as default active view	documents:write

9. Certificates & Trust Store (/api/v1/certificates)

Method	Endpoint	Description	Permission
GET	/certificates	List organization signing certificates	org:settings
GET	/certificates/default	Get or auto-provision default certificate	org:settings
POST	/certificates/generate	Generate a self-signed X.509 certificate with subject identity	org:manage
POST	/certificates/upload	Import Bring Your Own (BYO) certificate with chain	org:manage
GET	/certificates/:id	Retrieve certificate details, subject DN, and validity	org:settings
PUT	/certificates/:id/default	Set certificate as default organization signer	org:manage
DELETE	/certificates/:id	Revoke signing certificate	org:manage
GET	/certificates/trust-store	List managed TSA root and intermediate trust entries	org:settings
POST	/certificates/trust-store	Add custom TSA trust certificate	org:manage

10. Cryptographic Sealing & PAdES (/api/v1/signing)

Method	Endpoint	Description	Permission
POST	/signing/seal/:agreementId	Cryptographically seal completed agreement with PAdES B-T	documents:write
POST	/signing/batch	Batch seal up to 100 agreements in a single transaction	documents:write
POST	/signing/verify	Authenticated verification of document seal or PDF	documents:read

11. Public Verification Portal (/api/v1/verify)

Method	Endpoint	Description	Auth
GET	/verify/:token	Public verification query by token (GS-xxxxxxxx) or UUID	Public
POST	/verify/hash	Public verification query by document SHA-256 hash	Public
POST	/verify/file	Public verification query by uploaded PDF bytes	Public
GET	/verify/:token/certificate	Download Certificate of Cryptographic Authenticity	Public

12. Cloud Signature Consortium CSC v2.2 (/csc/v2)

Method	Endpoint	Description	Auth
POST	/csc/v2/info	Remote signing service capabilities and algorithms	Public
POST	/csc/v2/credentials/list	List remote signing credentials for tenant	OAuth Bearer
POST	/csc/v2/credentials/info	Certificate details, public key, and certificate chain	OAuth Bearer
POST	/csc/v2/credentials/authorize	Issue short-lived Server Authorisation Data (SAD) tokens	OAuth Bearer
POST	/csc/v2/signatures/signHash	Remote signature generation on pre-computed hashes	OAuth SAD
POST	/csc/v2/signatures/timestamp	Issue RFC 3161 timestamp tokens	OAuth Bearer