@inklok/api-spec 7.11.0 → 7.11.2

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.11.0"
+  version: "7.11.2"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -1278,12 +1278,13 @@ paths:
       operationId: exchangeMagicLink
       summary: Exchange a signing link for an access token
       description: |
-        Exchanges a signing link code for a short-lived bearer token that lets a
-        recipient view or sign an agreement.
+        Exchanges an agreement-link code for a short-lived party-scoped bearer token.
 
-        Codes can be used once. If a code has expired and the agreement is still
-        available, Inklok may send the recipient a refreshed signing link. Agreements
-        that can no longer be signed return an unavailable status.
+        SIGNING links are one-time capabilities. When an eligible signing link is no
+        longer usable, callers may request a replacement signing link. COMPLETED_VIEW
+        links are read-only capabilities that may be exchanged repeatedly during their
+        finite validity window so a client can renew an expired signer JWT. The backend
+        stored link purpose, not a URL query parameter, controls replay policy.
       tags:
         - Authentication
       requestBody:
@@ -1296,8 +1297,16 @@ paths:
               properties:
                 code:
                   type: string
+                request_reissue:
+                  type: boolean
+                  default: false
+                  description: |
+                    Requests a replacement link when an eligible one-time SIGNING code
+                    can no longer be used. COMPLETED_VIEW links are reusable and are not
+                    reissued through this mechanism.
             example:
               code: "7f3c9e2a-4d7a-4f35-a977-2d2b7e0fd9a1"
+              request_reissue: false
       responses:
         '200':
           description: Token issued, link reissued, or signing unavailable
@@ -1306,7 +1315,7 @@ paths:
               schema:
                 oneOf:
                   - type: object
-                    required: [access_token, token_type, expires_in]
+                    required: [access_token, token_type, expires_in, link_purpose, reusable]
                     properties:
                       access_token:
                         type: string
@@ -1316,6 +1325,13 @@ paths:
                       expires_in:
                         type: integer
                         description: Token lifetime in seconds
+                      link_purpose:
+                        type: string
+                        enum: [SIGNING, COMPLETED_VIEW]
+                        description: Server-authoritative purpose stored with the link record.
+                      reusable:
+                        type: boolean
+                        description: Whether the same code may be exchanged again during its validity window.
                   - type: object
                     required: [status, message]
                     properties:
@@ -1339,6 +1355,8 @@ paths:
                 access_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                 token_type: "Bearer"
                 expires_in: 900
+                link_purpose: "COMPLETED_VIEW"
+                reusable: true
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -3081,12 +3099,29 @@ paths:
       operationId: getSigningAgreement
       summary: Get signing details
       description: |
-        Returns the agreement details visible to the authenticated signer, including
-        the document, participant status, fields, and current signing state.
+        Returns the agreement details visible to the authorized participant. A party-scoped
+        signer bearer token uses the party embedded in the token and requires no query selectors.
+        An authenticated Cognito account may instead supply both `executionId` and `partyId` to
+        read a completed agreement when that exact party is durably bound to the authenticated
+        user. Completed account reads are read-only, expose only the matching USER envelope
+        projection, and never return guest invitation capability secrets.
       tags:
         - Signing
       security:
         - bearerAuth: []
+      parameters:
+        - name: executionId
+          in: query
+          required: false
+          description: Required with `partyId` only for authenticated account access to a completed agreement. Ignored for party-scoped signer tokens.
+          schema:
+            type: string
+        - name: partyId
+          in: query
+          required: false
+          description: Required with `executionId` only for authenticated account access. The party must already be durably bound to the authenticated USER.
+          schema:
+            type: string
       responses:
         '200':
           description: Agreement data for signer
@@ -3225,8 +3260,12 @@ paths:
                           description: JSON-serialized ScopedEncryptedFieldValue (v2). The server stores this string verbatim only after structural and authoritative binding validation.
                         required:
                           type: boolean
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
         '500':
           $ref: '#/components/responses/InternalServerError'
       x-inklok-lambda: signing-get-execution

package/package.json

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