@inklok/api-spec 7.9.3 → 7.11.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.9.3"
+  version: "7.11.0"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -746,6 +746,100 @@ paths:
         '500':
           $ref: '#/components/responses/InternalServerError'
 
+  /v1/platform/feature-flags:
+    get:
+      operationId: listPlatformFeatureFlags
+      summary: List feature flags
+      x-internal: true
+      x-visibility: internal
+      x-required-global-roles: [PLATFORM_ADMIN]
+      tags: [Platform]
+      responses:
+        '200':
+          description: Feature flag definitions
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [featureFlags]
+                properties:
+                  featureFlags:
+                    type: array
+                    items: { $ref: '#/components/schemas/FeatureFlag' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '500': { $ref: '#/components/responses/InternalServerError' }
+    post:
+      operationId: createPlatformFeatureFlag
+      summary: Create a feature flag
+      x-internal: true
+      x-visibility: internal
+      x-required-global-roles: [PLATFORM_ADMIN]
+      tags: [Platform]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/CreateFeatureFlagRequest' }
+      responses:
+        '201':
+          description: Created feature flag
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/FeatureFlag' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '409': { description: A feature flag with the key already exists }
+        '500': { $ref: '#/components/responses/InternalServerError' }
+
+  /v1/platform/feature-flags/{key}:
+    parameters:
+      - in: path
+        name: key
+        required: true
+        schema: { type: string, pattern: '^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$' }
+    get:
+      operationId: getPlatformFeatureFlag
+      summary: Get a feature flag
+      x-internal: true
+      x-visibility: internal
+      x-required-global-roles: [PLATFORM_ADMIN]
+      tags: [Platform]
+      responses:
+        '200':
+          description: Feature flag
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/FeatureFlag' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '500': { $ref: '#/components/responses/InternalServerError' }
+    patch:
+      operationId: updatePlatformFeatureFlag
+      summary: Update a feature flag
+      x-internal: true
+      x-visibility: internal
+      x-required-global-roles: [PLATFORM_ADMIN]
+      tags: [Platform]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/UpdateFeatureFlagRequest' }
+      responses:
+        '200':
+          description: Updated feature flag
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/FeatureFlag' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '500': { $ref: '#/components/responses/InternalServerError' }
+
   /platform/api-usage:
     get:
       operationId: getPlatformApiUsage
@@ -2473,6 +2567,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
@@ -2981,6 +3107,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
@@ -3037,6 +3167,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:
@@ -3905,6 +4048,7 @@ components:
         - orgs
         - emails
         - profile
+        - featureFlags
       properties:
         orgs:
           type: array
@@ -3923,6 +4067,50 @@ components:
               - PLATFORM_ADMIN
         profile:
           $ref: '#/components/schemas/BootstrapProfile'
+        featureFlags:
+          type: object
+          additionalProperties:
+            type: boolean
+          description: Effective feature availability for this principal; targeting and audit fields are not included.
+
+    FeatureFlag:
+      type: object
+      additionalProperties: false
+      required: [key, name, enabledForTestUsers, enabledForCustomers, enabledForApiKeys, createdAt, createdBy, updatedAt, updatedBy]
+      properties:
+        key: { type: string, pattern: '^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$' }
+        name: { type: string, minLength: 2, maxLength: 120 }
+        description: { type: string, maxLength: 1000 }
+        enabledForTestUsers: { type: boolean }
+        enabledForCustomers: { type: boolean }
+        enabledForApiKeys: { type: boolean }
+        createdAt: { type: string, format: date-time }
+        createdBy: { type: string }
+        updatedAt: { type: string, format: date-time }
+        updatedBy: { type: string }
+
+    CreateFeatureFlagRequest:
+      type: object
+      additionalProperties: false
+      required: [key, name]
+      properties:
+        key: { type: string, minLength: 2, maxLength: 80, pattern: '^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$' }
+        name: { type: string, minLength: 2, maxLength: 120 }
+        description: { type: string, maxLength: 1000 }
+        enabledForTestUsers: { type: boolean, default: false }
+        enabledForCustomers: { type: boolean, default: false }
+        enabledForApiKeys: { type: boolean, default: false }
+
+    UpdateFeatureFlagRequest:
+      type: object
+      additionalProperties: false
+      minProperties: 1
+      properties:
+        name: { type: string, minLength: 2, maxLength: 120 }
+        description: { type: string, nullable: true, maxLength: 1000 }
+        enabledForTestUsers: { type: boolean }
+        enabledForCustomers: { type: boolean }
+        enabledForApiKeys: { type: boolean }
 
     MeBillingSubscription:
       type: object
@@ -6044,7 +6232,7 @@ components:
 
     ExecutionStatus:
       type: string
-      enum: [pending, in_progress, completed, cancelled]
+      enum: [pending, in_progress, completed, cancelled, expired]
 
     ParticipantStatus:
       type: string
@@ -6149,8 +6337,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
@@ -6185,6 +6381,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]
@@ -6203,6 +6458,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
@@ -6216,7 +6478,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
@@ -6773,6 +7035,7 @@ components:
           currentStep,
           totalSteps,
           createdAt,
+          expiresAt,
           updatedAt,
           pdfEngineVersion,
           agreementTitle,
@@ -6805,6 +7068,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
@@ -6897,6 +7165,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.9.3",
+  "version": "7.11.0",
   "description": "Canonical OpenAPI specification for the Inklok public API.",
   "main": "openapi.yaml",
   "license": "MIT",