{
  "openapi": "3.1.0",
  "info": {
    "title": "LikenessID Partner API \u2014 Design Preview",
    "version": "0.1.0-draft",
    "description": "PROPOSED CONTRACT ONLY. No external endpoint, credential issuance or partner service is deployed. Examples are fictional. A partner must enforce denial, unresolved identity, authentication failure and service failure by blocking or pausing the request. Approval applies only to the specific approved action and license scope. A check does not grant new rights or reserve one-time usage. Production requires atomic reservation and release controls, authenticated brand delegation, rate limits, revocation handling and audit records. This API does not identify arbitrary faces or police non-integrated platforms."
  },
  "x-likeness-status": "design-preview-not-deployed",
  "servers": [
    {
      "url": "https://api.likeness.invalid",
      "description": "Intentionally non-routable example; production base URL is not yet issued."
    }
  ],
  "paths": {
    "/v1/permissions/check": {
      "post": {
        "operationId": "checkLikenessPermission",
        "summary": "Proposed permission check for a single intended use",
        "description": "Read-only authorization decision. Resolve the submitted ID, verify creator identity/consent/freeze status and check license ownership, approval, payment, active term, permitted category/format, exclusivity and usage availability. Never treat registry absence as permission. Recheck before releasing content; production one-time usage must be reserved atomically through a separate lifecycle before concurrent requests can be allowed.",
        "security": [
          {
            "PartnerBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PermissionRequest"
              },
              "example": {
                "likeness_id": "LID-DEMO-0001",
                "license_id": "LIC-DEMO-0001",
                "brand_id": "BRAND-DEMO-0001",
                "action": "generate_image",
                "category": "Beauty & skincare",
                "platform_request_id": "request_demo_0001"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Permission decision for this request only. A denial is a valid decision response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionDecision"
                },
                "example": {
                  "decision_id": "decision_demo_0001",
                  "allowed": false,
                  "reason_code": "LIKENESS_FROZEN",
                  "likeness_id": "LID-DEMO-0001",
                  "license_id": "LIC-DEMO-0001",
                  "action": "generate_image",
                  "platform_request_id": "request_demo_0001"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid partner credential. Do not permit the attempted use."
          },
          "403": {
            "description": "Partner is not authorized for this brand, identity or license. Do not permit the attempted use."
          },
          "422": {
            "description": "Invalid or incomplete intended-use request. Do not permit the attempted use."
          },
          "429": {
            "description": "Rate limit reached. Pause and retry; do not treat as approval."
          },
          "503": {
            "description": "Registry or decision service unavailable. Pause and retry; do not treat as approval."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PartnerBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Planned scoped server-to-server partner credential. Credential issuance is not yet available. Keep credentials on the integrating server."
      }
    },
    "schemas": {
      "PermissionRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "likeness_id",
          "license_id",
          "brand_id",
          "action",
          "category",
          "platform_request_id"
        ],
        "properties": {
          "likeness_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "license_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "brand_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "The authenticated partner must be independently authorized to act for this brand; a supplied ID does not grant access."
          },
          "action": {
            "type": "string",
            "enum": [
              "generate_image",
              "generate_video",
              "commercial_use"
            ]
          },
          "category": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Must match the advertising category in the approved license."
          },
          "platform_request_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Stable identifier for the attempted action. A permission check does not itself reserve or consume licensed usage."
          }
        }
      },
      "PermissionDecision": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "decision_id",
          "allowed",
          "reason_code",
          "likeness_id",
          "license_id",
          "action",
          "platform_request_id"
        ],
        "properties": {
          "decision_id": {
            "type": "string"
          },
          "allowed": {
            "type": "boolean",
            "description": "True only for the evaluated request and approved license scope; never blanket permission."
          },
          "reason_code": {
            "type": "string",
            "enum": [
              "APPROVED_SCOPE",
              "LIKENESS_FROZEN",
              "LICENSE_NOT_AUTHORIZED",
              "LICENSE_EXPIRED",
              "SCOPE_NOT_ALLOWED",
              "IDENTITY_UNRESOLVED",
              "REGISTRY_UNAVAILABLE"
            ]
          },
          "likeness_id": {
            "type": "string"
          },
          "license_id": {
            "type": "string"
          },
          "action": {
            "type": "string",
            "enum": [
              "generate_image",
              "generate_video",
              "commercial_use"
            ]
          },
          "platform_request_id": {
            "type": "string"
          }
        }
      }
    }
  }
}