@inklok/api-spec 7.5.2 → 7.6.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.5.2"
+  version: "7.6.1"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -408,6 +408,102 @@ 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.
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 25
+          description: Maximum number of organizations to return for browse/search results.
+        - in: query
+          name: cursor
+          schema:
+            type: string
+          description: Opaque pagination cursor returned by the previous response.
+      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
@@ -3911,6 +4007,315 @@ 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
+        - entitlement
+      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
+        entitlement:
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/PlatformEntitlementOrganizationSummary'
+
+    PlatformEntitlementOrganizationSummary:
+      type: object
+      required:
+        - plan
+        - subscriptionStatus
+        - source
+        - includedSeats
+        - additionalSeats
+        - effectiveSeatLimit
+        - maxApiRequestsPerMinute
+        - hasCustomSeatOverride
+        - hasCustomApiLimit
+      properties:
+        plan:
+          $ref: '#/components/schemas/PlatformPlan'
+        subscriptionStatus:
+          type: string
+        source:
+          type: string
+          enum:
+            - stored
+            - plan-default
+        includedSeats:
+          type: integer
+          nullable: true
+          minimum: 0
+        additionalSeats:
+          type: integer
+          minimum: 0
+        effectiveSeatLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+        maxApiRequestsPerMinute:
+          type: integer
+          nullable: true
+          minimum: 0
+        hasCustomSeatOverride:
+          type: boolean
+        hasCustomApiLimit:
+          type: boolean
+
+    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
+        - nextCursor
+        - generatedAt
+      properties:
+        organizations:
+          type: array
+          items:
+            $ref: '#/components/schemas/PlatformEntitlementOrganization'
+        selected:
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/PlatformEntitlementDetail'
+        nextCursor:
+          type: string
+          nullable: true
+        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.2",
+  "version": "7.6.1",
   "description": "Canonical OpenAPI specification for the Inklok public API.",
   "main": "openapi.yaml",
   "license": "MIT",