@inklok/api-spec 7.5.1 → 7.6.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.5.1"
+  version: "7.6.0"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -408,6 +408,89 @@ paths:
         '500':
           $ref: '#/components/responses/InternalServerError'
 
+  /platform/entitlements:
+    get:
+      operationId: getPlatformEntitlements
+      summary: Lookup Platform entitlements
+      x-visibility: internal
+      description: |
+        Looks up organization entitlement information for internal operators.
+        Requires an authorized platform administrator.
+      x-required-global-roles: [PLATFORM_ADMIN]
+      tags:
+        - Platform
+      parameters:
+        - in: query
+          name: orgId
+          schema:
+            type: string
+          description: Organization ID to inspect.
+        - in: query
+          name: accountId
+          schema:
+            type: string
+          description: Customer account identifier to inspect.
+        - in: query
+          name: q
+          schema:
+            type: string
+          description: Organization name or identifier search.
+      responses:
+        '200':
+          description: Successfully retrieved Platform entitlement information
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlatformEntitlementLookupResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /platform/entitlements/{orgId}:
+    patch:
+      operationId: updatePlatformEntitlement
+      summary: Update Platform seat entitlements
+      x-visibility: internal
+      description: |
+        Updates editable seat entitlement values for an organization.
+        effectiveSeatLimit is always derived server-side.
+        Requires an authorized platform administrator.
+      x-required-global-roles: [PLATFORM_ADMIN]
+      tags:
+        - Platform
+      parameters:
+        - in: path
+          name: orgId
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PlatformEntitlementUpdateRequest'
+      responses:
+        '200':
+          description: Successfully updated Platform entitlement information
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlatformEntitlementDetail'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
   /platform/ses:
     get:
       operationId: getPlatformSes
@@ -2202,19 +2285,30 @@ paths:
       x-visibility: internal
       description: |
         Returns simulated emails generated by sandbox agreement workflows visible
-        to the authenticated account or the caller's sandbox API-key organization.
+        to the authenticated Cognito user account. API key authentication is not
+        supported for Sandbox Inbox.
         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. List items are summary-only and do not
-        include rendered email bodies.
+        include rendered email bodies. When `messageId` is supplied, the response
+        includes sanitized rendered preview content with executable hrefs, magic
+        links, signer tokens, signing URLs, and replay-enabling identifiers removed.
+        Sanitization is applied to every user-visible Sandbox Inbox field in the
+        response, including subject, preview text, participant labels, agreement
+        titles, and rendered bodies. Email event records remain unchanged.
       x-required-roles: [workflow-editor, workflow-operator, agreement-auditor, organization-admin, platform-super-admin]
-      x-required-scopes: [agreements:read]
       tags:
         - Me
       parameters:
+        - name: messageId
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Optional Sandbox Inbox message identifier. When supplied, returns a sanitized message detail instead of a paginated summary list.
         - name: limit
           in: query
           required: false
@@ -2233,11 +2327,13 @@ paths:
           description: Opaque pagination cursor returned by a previous response.
       responses:
         '200':
-          description: Simulated Sandbox agreement emails for the authenticated user
+          description: Simulated Sandbox agreement emails or sanitized message detail for the authenticated user
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/SandboxInboxResponse'
+                oneOf:
+                  - $ref: '#/components/schemas/SandboxInboxResponse'
+                  - $ref: '#/components/schemas/SandboxInboxDetail'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
@@ -3311,10 +3407,11 @@ components:
         email:
           type: string
           nullable: true
-          format: email
+          description: Sanitized recipient address preview. Token-like values and replay-enabling identifiers are removed at retrieval time.
         label:
           type: string
           nullable: true
+          description: Sanitized participant display label. Token-like values and replay-enabling identifiers are removed at retrieval time.
 
     SandboxInboxItem:
       type: object
@@ -3336,6 +3433,7 @@ components:
         agreementTitle:
           type: string
           nullable: true
+          description: Sanitized agreement title preview. Token-like values and replay-enabling identifiers are removed at retrieval time.
         eventType:
           type: string
           enum: [SIGN_REQUEST, NEXT_STEP, COMPLETED, REMINDER, SIGNING_REMINDER, AGREEMENT_REMINDER]
@@ -3344,15 +3442,35 @@ components:
         sender:
           type: string
           nullable: true
+          description: Sanitized sender preview. Token-like values and replay-enabling identifiers are removed at retrieval time.
         subject:
           type: string
           nullable: true
+          description: Sanitized email subject preview. Token-like values, signing URLs, and replay-enabling identifiers are removed at retrieval time.
         preview:
           type: string
+          description: Sanitized list preview. Token-like values, signing URLs, and replay-enabling identifiers are removed at retrieval time.
         sentAt:
           type: string
           format: date-time
 
+    SandboxInboxDetail:
+      allOf:
+        - $ref: '#/components/schemas/SandboxInboxItem'
+        - type: object
+          required:
+            - htmlBody
+            - textBody
+          properties:
+            htmlBody:
+              type: string
+              nullable: true
+              description: Sanitized rendered HTML preview. Executable hrefs, magic links, signer tokens, signing URLs, and replay-enabling identifiers are removed at retrieval time.
+            textBody:
+              type: string
+              nullable: true
+              description: Sanitized plain-text preview. Magic links, signer tokens, signing URLs, and replay-enabling identifiers are removed at retrieval time.
+
     SandboxInboxResponse:
       type: object
       required:
@@ -3876,6 +3994,264 @@ components:
           type: string
           format: date-time
 
+    PlatformPlan:
+      type: string
+      enum:
+        - free
+        - pro
+        - team
+        - enterprise
+
+    PlatformPlanLimits:
+      type: object
+      required:
+        - includedSeats
+        - additionalSeats
+        - effectiveSeatLimit
+        - maxProductionAgreementsLifetime
+        - maxEmailsPerDay
+        - maxAgreementCreatesPerMinute
+        - maxApiRequestsPerMinute
+      properties:
+        includedSeats:
+          type: integer
+          nullable: true
+          minimum: 0
+        additionalSeats:
+          type: integer
+          minimum: 0
+        effectiveSeatLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+          readOnly: true
+        maxProductionAgreementsLifetime:
+          type: integer
+          nullable: true
+          minimum: 0
+        maxEmailsPerDay:
+          type: integer
+          nullable: true
+          minimum: 0
+        maxAgreementCreatesPerMinute:
+          type: integer
+          nullable: true
+          minimum: 0
+        maxApiRequestsPerMinute:
+          type: integer
+          nullable: true
+          minimum: 0
+
+    PlatformEntitlement:
+      type: object
+      required:
+        - accountId
+        - plan
+        - subscriptionStatus
+        - source
+        - limits
+      properties:
+        accountId:
+          type: string
+        plan:
+          $ref: '#/components/schemas/PlatformPlan'
+        subscriptionStatus:
+          type: string
+        source:
+          type: string
+          enum:
+            - stored
+            - plan-default
+        limits:
+          $ref: '#/components/schemas/PlatformPlanLimits'
+
+    PlatformEntitlementOrganization:
+      type: object
+      required:
+        - orgId
+        - name
+        - type
+        - accountId
+        - isPersonal
+        - createdAt
+      properties:
+        orgId:
+          type: string
+        name:
+          type: string
+          nullable: true
+        type:
+          type: string
+          enum:
+            - PRODUCTION
+            - SANDBOX
+        accountId:
+          type: string
+          nullable: true
+        isPersonal:
+          type: boolean
+        createdAt:
+          type: string
+          format: date-time
+
+    PlatformEntitlementSeats:
+      type: object
+      required:
+        - includedSeats
+        - additionalSeats
+        - effectiveSeatLimit
+        - reservedSeats
+        - activeMembers
+        - pendingInvitations
+      properties:
+        includedSeats:
+          type: integer
+          nullable: true
+          minimum: 0
+        additionalSeats:
+          type: integer
+          minimum: 0
+        effectiveSeatLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+          readOnly: true
+        reservedSeats:
+          type: integer
+          minimum: 0
+        activeMembers:
+          type: integer
+          minimum: 0
+        pendingInvitations:
+          type: integer
+          minimum: 0
+
+    PlatformEntitlementMember:
+      type: object
+      required:
+        - userId
+        - displayName
+        - email
+        - role
+        - status
+        - joinedAt
+      properties:
+        userId:
+          type: string
+        displayName:
+          type: string
+        email:
+          type: string
+        role:
+          $ref: '#/components/schemas/Role'
+        status:
+          type: string
+          enum:
+            - active
+            - inactive
+        joinedAt:
+          type: string
+
+    PlatformEntitlementUsage:
+      type: object
+      required:
+        - usageTrackingConfigured
+        - productionAgreementsLifetime
+        - productionAgreementsLimit
+        - maxApiRequestsPerMinute
+      properties:
+        usageTrackingConfigured:
+          type: boolean
+        productionAgreementsLifetime:
+          type: integer
+          nullable: true
+          minimum: 0
+        productionAgreementsLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+        maxApiRequestsPerMinute:
+          type: integer
+          nullable: true
+          minimum: 0
+
+    PlatformApiLimitReadiness:
+      type: object
+      required:
+        - maxApiRequestsPerMinute
+        - customApiOverridesReady
+        - usageVisibilityReady
+      properties:
+        maxApiRequestsPerMinute:
+          type: integer
+          nullable: true
+          minimum: 0
+        customApiOverridesReady:
+          type: boolean
+        usageVisibilityReady:
+          type: boolean
+
+    PlatformEntitlementDetail:
+      type: object
+      required:
+        - organization
+        - entitlement
+        - seats
+        - members
+        - usage
+        - apiLimitReadiness
+        - generatedAt
+      properties:
+        organization:
+          $ref: '#/components/schemas/PlatformEntitlementOrganization'
+        entitlement:
+          $ref: '#/components/schemas/PlatformEntitlement'
+        seats:
+          $ref: '#/components/schemas/PlatformEntitlementSeats'
+        members:
+          type: array
+          items:
+            $ref: '#/components/schemas/PlatformEntitlementMember'
+        usage:
+          $ref: '#/components/schemas/PlatformEntitlementUsage'
+        apiLimitReadiness:
+          $ref: '#/components/schemas/PlatformApiLimitReadiness'
+        generatedAt:
+          type: string
+          format: date-time
+
+    PlatformEntitlementLookupResponse:
+      type: object
+      required:
+        - organizations
+        - selected
+        - generatedAt
+      properties:
+        organizations:
+          type: array
+          items:
+            $ref: '#/components/schemas/PlatformEntitlementOrganization'
+        selected:
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/PlatformEntitlementDetail'
+        generatedAt:
+          type: string
+          format: date-time
+
+    PlatformEntitlementUpdateRequest:
+      type: object
+      additionalProperties: false
+      properties:
+        additionalSeats:
+          type: integer
+          minimum: 0
+        includedSeats:
+          type: integer
+          nullable: true
+          minimum: 0
+          description: Enterprise custom included seat value. Ignored for non-Enterprise plans.
+
     PlatformCostsResponse:
       type: object
       required:

package/package.json

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