@inklok/api-spec 7.11.0 → 7.11.1

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.1"
   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':

package/package.json

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