@inklok/api-spec 7.10.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.10.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':
@@ -2567,6 +2585,38 @@ paths:
         '500':
           $ref: '#/components/responses/InternalServerError'
 
+  /v1/templates/{workflowId}/agreements/prepare:
+    post:
+      operationId: prepareAgreementGuestInvitationsV1
+      summary: Prepare an agreement cryptographic context
+      description: |
+        First stage of agreement creation. Reserves the authoritative execution and party IDs,
+        then returns short-lived one-time bootstrap material used by the client to construct the
+        guest invitation capabilities required by the create/finalize request. Preparation does
+        not create a Vault-visible agreement or consume agreement creation usage.
+
+        The response must be finalized against the same workflow, organization, and authenticated
+        principal before `expiresIn` elapses. Raw bootstrap values are never persisted by Inklok.
+      x-required-roles: [workflow-operator, organization-admin]
+      x-required-scopes: [agreements:write]
+      tags: [Agreements]
+      parameters:
+        - name: workflowId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: Short-lived authoritative context and one-time material for agreement creation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PrepareGuestInvitationsResponse'
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '500': { $ref: '#/components/responses/InternalServerError' }
+
   /v1/agreements/{executionId}:
     get:
       operationId: getAgreementV1
@@ -3075,6 +3125,10 @@ paths:
                 properties:
                   execution_id:
                     type: string
+                  expires_at:
+                    type: string
+                    format: date-time
+                    description: Immutable agreement deadline; signing is rejected at or after this instant.
                   agreement_title:
                     type: string
                     nullable: true
@@ -3131,6 +3185,19 @@ paths:
                             type: string
                             example: RSA-OAEP-256
                         description: Encrypted document key metadata for this signer
+                  key_scopes:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KeyScope'
+                  key_envelopes:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/KeyEnvelope'
+                  invitation_capabilities:
+                    type: array
+                    description: Active agreement-specific guest capabilities. Only the authenticated party receives its encrypted private-key package; other parties expose public addressing data only.
+                    items:
+                      $ref: '#/components/schemas/GuestInvitationCapability'
                   parties:
                     type: array
                     items:
@@ -6183,7 +6250,7 @@ components:
 
     ExecutionStatus:
       type: string
-      enum: [pending, in_progress, completed, cancelled]
+      enum: [pending, in_progress, completed, cancelled, expired]
 
     ParticipantStatus:
       type: string
@@ -6288,8 +6355,16 @@ components:
 
     CreateExecutionRequest:
       type: object
-      required: [agreementTitle, participants, crypto]
+      required: [agreementTitle, participants, crypto, preparedExecutionId, guestInvitations]
       properties:
+        preparedExecutionId:
+          type: string
+          format: uuid
+        guestInvitations:
+          type: array
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/CreateGuestInvitationInput'
         agreementTitle:
           type: string
           minLength: 1
@@ -6324,6 +6399,65 @@ components:
               items:
                 $ref: '#/components/schemas/ManagedRecoveryCapability'
 
+    PrepareGuestInvitationsResponse:
+      type: object
+      required: [executionId, expiresIn, parties]
+      properties:
+        executionId: { type: string, format: uuid }
+        expiresIn: { type: integer }
+        parties:
+          type: array
+          items:
+            type: object
+            required: [roleId, partyId, authorizationCode, bootstrapSecret]
+            properties:
+              roleId: { type: string }
+              partyId: { type: string }
+              authorizationCode: { type: string, writeOnly: true }
+              bootstrapSecret: { type: string, writeOnly: true }
+
+    CreateGuestInvitationInput:
+      type: object
+      required: [partyId, authorizationCode, bootstrapSecret, capability]
+      properties:
+        partyId: { type: string }
+        authorizationCode: { type: string, writeOnly: true }
+        bootstrapSecret: { type: string, writeOnly: true }
+        capability:
+          $ref: '#/components/schemas/GuestInvitationCapabilityInput'
+
+    GuestInvitationCapabilityInput:
+      type: object
+      required: [protocol, invitationKeyId, publicKeySpki, encryptedPrivateKey, iv, salt, aad, kdf, cipher]
+      properties:
+        protocol: { type: string, enum: [inklok-guest-invitation-v1] }
+        invitationKeyId: { type: string }
+        publicKeySpki: { type: string }
+        encryptedPrivateKey: { type: string }
+        iv: { type: string }
+        salt: { type: string }
+        aad: { type: string }
+        kdf: { type: string, enum: [HKDF-SHA-256] }
+        cipher: { type: string, enum: [AES-256-GCM] }
+
+    GuestInvitationCapability:
+      type: object
+      required: [protocol, partyId, invitationKeyId, invitationPrincipalId, publicKeySpki, status]
+      properties:
+        protocol: { type: string, enum: [inklok-guest-invitation-v1] }
+        partyId: { type: string }
+        invitationKeyId: { type: string }
+        invitationPrincipalId: { type: string }
+        publicKeySpki: { type: string }
+        encryptedPrivateKey: { type: string }
+        iv: { type: string }
+        salt: { type: string }
+        aad: { type: string }
+        kdf: { type: string, enum: [HKDF-SHA-256] }
+        cipher: { type: string, enum: [AES-256-GCM] }
+        status: { type: string, enum: [active] }
+        createdAt: { type: string, format: date-time }
+
     KeyScope:
       type: object
       required: [keyScopeId, type, version]
@@ -6342,6 +6476,13 @@ components:
           type: array
           items:
             type: string
+        fieldIds:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          description: Protected workflow fields assigned to this scope. Required by new agreement creation clients so one party may own multiple scopes with different sharing policies.
+          items:
+            type: string
         authorizationPolicy:
           type: object
           additionalProperties: true
@@ -6355,7 +6496,7 @@ components:
         protectionMode:
           type: string
           enum: [MANAGED, STRICT_ZK]
-          description: Current signing creation accepts MANAGED only. STRICT_ZK is reserved and not enabled.
+          description: Agreement signing creation requires STRICT_ZK. MANAGED remains in the response model for legacy records.
         createdAt:
           type: string
           format: date-time
@@ -6912,6 +7053,7 @@ components:
           currentStep,
           totalSteps,
           createdAt,
+          expiresAt,
           updatedAt,
           pdfEngineVersion,
           agreementTitle,
@@ -6944,6 +7086,11 @@ components:
           type: string
           format: date-time
           readOnly: true
+        expiresAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Immutable deadline exactly 30 days after agreement creation.
         updatedAt:
           type: string
           format: date-time
@@ -7036,6 +7183,11 @@ components:
         executionId:
           type: string
           description: The identifier of an agreement instance.
+        expiresAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: Immutable agreement deadline for active agreements.
         organizationId:
           type: string
           nullable: true

package/package.json

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