@inklok/api-spec 7.2.1 → 7.3.0

package/openapi.yaml

@@ -8,7 +8,7 @@ info:
     Authenticate using an API key or bearer token, then use the resources below to manage
     templates, agreements, documents, and signing. For your first integration, start with
     the Quick Start guide.
-  version: "7.2.1"
+  version: "7.3.0"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -2051,9 +2051,10 @@ paths:
       summary: Resolve a party signing session
       x-visibility: internal
       description: >
-        Returns a valid signing URL for the requested execution party when that party
-        is the active signer for the agreement. Creates a new magic link if necessary.
-      x-required-roles: [workflow-editor, workflow-operator, agreement-auditor, organization-admin, platform-super-admin]
+        Returns a short-lived signer session for the requested execution party when
+        the authenticated Cognito user is the active signer for the agreement. This
+        endpoint never creates or returns magic links.
+      x-required-roles: []
       tags:
         - Agreements
       parameters:
@@ -2082,10 +2083,19 @@ paths:
               schema:
                 type: object
                 required:
-                  - signingUrl
+                  - signerToken
                 properties:
-                  signingUrl:
+                  signerToken:
+                    type: string
+                  tokenType:
+                    type: string
+                    example: Bearer
+                  expiresIn:
+                    type: integer
+                    minimum: 1
+                  expiresAt:
                     type: string
+                    format: date-time
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
@@ -2188,18 +2198,18 @@ paths:
   /me/sandbox/inbox:
     get:
       operationId: listMeSandboxInbox
-      summary: List simulated agreement emails from the current user's sandbox
+      summary: List simulated agreement emails from Sandbox Inbox
       x-visibility: internal
       description: |
         Returns simulated emails generated by sandbox agreement workflows visible
-        to the authenticated account. When an agreement action would normally send
-        a notification to a party, Inklok creates a simulated email in Sandbox Inbox
-        instead. No emails are sent to recipients.
-        Recipient email address is not used for visibility. The endpoint uses an
-        explicit allowlist of agreement lifecycle email event types and never returns
-        authentication, identity, invitation, security, or generic outbound email history.
-        Each item includes the rendered simulated email HTML and plain-text body when
-        the simulated email content is available.
+        to the authenticated account or the caller's sandbox API-key organization.
+        When an agreement action would normally send a notification to a party,
+        Inklok creates a simulated email in Sandbox Inbox instead. No emails are
+        sent to recipients. Recipient email address is not used for visibility.
+        The endpoint uses an explicit allowlist of agreement lifecycle email event
+        types and never returns authentication, identity, invitation, security, or
+        generic outbound email history. Each item includes the rendered simulated
+        email HTML and plain-text body when the simulated email content is available.
       x-required-roles: [workflow-editor, workflow-operator, agreement-auditor, organization-admin, platform-super-admin]
       x-required-scopes: [agreements:read]
       tags:
@@ -2480,6 +2490,18 @@ paths:
                 properties:
                   execution_id:
                     type: string
+                  agreement_title:
+                    type: string
+                    nullable: true
+                    description: Human-readable title for this agreement.
+                  agreement_message:
+                    type: string
+                    nullable: true
+                    description: Shared message from the sender for all recipients.
+                  recipient_message:
+                    type: string
+                    nullable: true
+                    description: Private message for the authenticated signer only.
                   version:
                     type: string
                     description: Rendering engine version for this agreement
@@ -2576,13 +2598,14 @@ paths:
       operationId: signingInitiate
       summary: Create a signing session
       description: >
-        Creates a short-lived signing token for the specified agreement participant.
-        Use the token to let that recipient review and complete their signing step.
+        Creates a short-lived signing token for the specified agreement participant
+        only when the caller is that participant. API-key authentication is not
+        supported for this endpoint.
       tags:
         - Signing
       security:
         - bearerAuth: []
-      x-required-scopes: [agreements:write]
+      x-required-roles: []
       requestBody:
         required: true
         content:
@@ -4694,11 +4717,26 @@ components:
         name:
           type: string
           nullable: true
+        recipientMessage:
+          type: string
+          nullable: true
+          maxLength: 5000
+          description: Optional private message visible only to this recipient.
 
     CreateExecutionRequest:
       type: object
-      required: [participants, crypto]
+      required: [agreementTitle, participants, crypto]
       properties:
+        agreementTitle:
+          type: string
+          minLength: 1
+          maxLength: 160
+          description: Human-readable title for this agreement.
+        agreementMessage:
+          type: string
+          nullable: true
+          maxLength: 5000
+          description: Optional shared message visible to all recipients.
         participants:
           type: array
           minItems: 1
@@ -5047,6 +5085,16 @@ components:
           type: integer
           minimum: 1
           readOnly: true
+        agreementTitle:
+          type: string
+          nullable: true
+          readOnly: true
+          description: Human-readable title for this agreement.
+        agreementMessage:
+          type: string
+          nullable: true
+          readOnly: true
+          description: Shared message from the sender for all recipients.
         pdfEngineVersion:
           type: integer
           minimum: 1
@@ -5092,6 +5140,7 @@ components:
           createdAt,
           updatedAt,
           pdfEngineVersion,
+          agreementTitle,
           participants,
           placeholderValues,
         ]
@@ -5107,6 +5156,16 @@ components:
         status:
           $ref: '#/components/schemas/ExecutionStatus'
           readOnly: true
+        agreementTitle:
+          type: string
+          nullable: true
+          readOnly: true
+          description: Human-readable title for this agreement.
+        agreementMessage:
+          type: string
+          nullable: true
+          readOnly: true
+          description: Shared message from the sender for all recipients.
         createdAt:
           type: string
           format: date-time
@@ -5173,6 +5232,10 @@ components:
         color:
           type: string
           nullable: true
+        recipientMessage:
+          type: string
+          nullable: true
+          description: Private message for this recipient. Signer-scoped responses only include the current signer's message.
 
     ExecutionParticipantSearchResult:
       type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inklok/api-spec",
-  "version": "7.2.1",
+  "version": "7.3.0",
   "description": "Canonical OpenAPI specification for the Inklok public API.",
   "main": "openapi.yaml",
   "license": "MIT",