ConsentContext

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/picaos/main/json-schema/picaos-consent-context-schema.json",
  "title": "ConsentContext",
  "description": "Everything the connect card needs to render one consent ceremony.",
  "x-generated": "2026-10-21",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/picaos-api-openapi.json#/components/schemas/ConsentContext",
  "properties": {
    "allowAll": {
      "description": "True when the ceremony named no permission set (or the allow-all set),\nso the app offers the whole catalog. The card renders the offerable\ncatalog as prospective in that case; without this it could not tell\n\"everything\" from an enumerated set that resolved to zero\nconnectors, which activate would then refuse.",
      "type": "boolean"
    },
    "clientName": {
      "description": "Display name of the app asking for access.",
      "type": "string"
    },
    "connectors": {
      "description": "The connectors the ceremony offers, resolved from the permission-set\nsnapshot frozen onto the placeholder at authorize time. Empty for an\nallow-all ceremony and for an enumerated set whose connectors are all\ndelisted; `allow_all` is what tells the two apart.",
      "items": {
        "$ref": "#/$defs/ResolvedConnectorView"
      },
      "type": "array"
    },
    "frameAncestors": {
      "description": "The origins allowed to frame this card, as a `frame-ancestors` source\nlist: the client's registered redirect-URI origins, or `'none'` when it\nhas none that parse.\n\n**Core cannot enforce this, and that is why it is here.** A\n`frame-ancestors` policy governs the response it rides on, and the card\ndocument is served by the frontend, not by this server - a policy on the\nredirect that sends a browser there protects nothing. Whoever serves the\ncard has to emit it, and this is where they get the answer: the ceremony\nnames the client, the client's redirect origins are already its proven\nproperty, and both are known here.",
      "type": "string"
    },
    "loginHint": {
      "description": "Email the authorize URL suggested, for the card to pre-fill its sign-in\nfield. Never a restriction: a user who types a different address signs\nin as that one.",
      "type": [
        "string",
        "null"
      ]
    },
    "logoUrl": {
      "description": "The app's logo, as its owner registered it. `None` when they registered\nnone, which is the card's cue to fall back to whatever placeholder it\ndraws.",
      "type": [
        "string",
        "null"
      ]
    },
    "reason": {
      "description": "Why this app says it is asking, as its owner wrote it - see\n[`ConsentReason`]. `None` when they set none, which renders the screen\nexactly as it did before this existed.\n\nRead from the client, not from the request, so it is the app's own\nwords rather than the link-sender's.",
      "type": [
        "string",
        "null"
      ]
    },
    "viewer": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/ConsentViewer",
          "description": "`None` until somebody signs in, which serializes as JSON `null` and is\nwhat tells the card to render sign-in.\n\nDeliberately **not** `skip_serializing_if`: the absence of a viewer is\nthe answer this endpoint exists to give, so the key has to be present\nand null rather than missing. A card written against the documented\ncontract - or a generated client typing this as `Viewer | null` - would\nnever see the field at all if it were skipped, and so would never\nrender sign-in."
        }
      ]
    }
  },
  "required": [
    "clientName",
    "connectors",
    "allowAll",
    "frameAncestors"
  ],
  "type": "object",
  "$defs": {
    "AllowedActionView": {
      "properties": {
        "id": {
          "description": "The action's **`system_id`**, not its row id.\n\nThis is the identifier a rule's `actionIds` carries and the one both\nthe permission-set editor and the consent submission are validated\nagainst, so it is the only id a client can send back. Publishing the\nrow id instead round-trips into an action that resolves to a different\nconnector, which consent now refuses as foreign.",
          "type": "string"
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "title"
      ],
      "type": "object"
    },
    "ConnectionDefinitionId": {
      "description": "Prefixed ID with 'conn_def' prefix (e.g., 'conn_def_1C'), also accepts raw integer",
      "type": "string"
    },
    "ConsentOrganization": {
      "description": "One organization a consent ceremony can be scoped to.",
      "properties": {
        "id": {
          "format": "uuid",
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ],
      "type": "object"
    },
    "ConsentProject": {
      "description": "One project a consent ceremony can be scoped to, and the organization it\nbelongs to.",
      "properties": {
        "id": {
          "format": "uuid",
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "organizationId": {
          "format": "uuid",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "organizationId"
      ],
      "type": "object"
    },
    "ConsentTenancy": {
      "description": "The tenants a user may grant a consent ceremony against.",
      "properties": {
        "organizations": {
          "items": {
            "$ref": "#/$defs/ConsentOrganization"
          },
          "type": "array"
        },
        "projects": {
          "items": {
            "$ref": "#/$defs/ConsentProject"
          },
          "type": "array"
        }
      },
      "required": [
        "organizations",
        "projects"
      ],
      "type": "object"
    },
    "ConsentViewer": {
      "description": "Who the ceremony is being shown to. Absent - JSON `null` - is what tells\nthe card to render sign-in.",
      "properties": {
        "email": {
          "description": "The address the card labels the session with - \"signed in as …\".\n\nTheir own, and only ever their own: this is populated from the row the\nsession's user id names, after the ceremony has been proved claimable by\nthat same user, so a state-key holder cannot read it for anybody else.",
          "type": "string"
        },
        "tenancy": {
          "$ref": "#/$defs/ConsentTenancy",
          "description": "The tenants this user may scope the grant to. Only ever populated for a\nsigned-in viewer, because it is their own tenancy."
        },
        "userId": {
          "format": "uuid",
          "type": "string"
        }
      },
      "required": [
        "userId",
        "email",
        "tenancy"
      ],
      "type": "object"
    },
    "EnvelopeView": {
      "description": "What a connector rule lets through, as every surface publishes it.\n\n**Absent means unrestricted, on the way out and on the way back in.** A\nsubmission that omits `methods` asks for *every* method, so a client offered\na narrowed connector sends this envelope back verbatim or its submission is\nrefused as widening - and \"copy what is there, omit what is not\" therefore\nproduces a valid submission in every case. Published without it, a narrowed\noffer was impossible to accept at all.\n\nOne type rather than one per surface: the held rule and the ask it is\nbounded by are the same envelope answering the same round-trip contract, and\ntwo definitions of it would eventually disagree.",
      "properties": {
        "allowedActions": {
          "description": "Resolved titles for the rule's `action_ids`, present only when the rule\nnarrows to a specific set (i.e. a custom rule). `None` means every\naction on the connector, which a customer-facing UI labels\ngenerically rather than listing.",
          "items": {
            "$ref": "#/$defs/AllowedActionView"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "methods": {
          "items": {
            "$ref": "#/$defs/Method"
          },
          "type": [
            "array",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "Method": {
      "enum": [
        "OPTIONS",
        "GET",
        "POST",
        "PUT",
        "DELETE",
        "HEAD",
        "TRACE",
        "CONNECT",
        "PATCH"
      ],
      "type": "string"
    },
    "ResolvedConnectorView": {
      "allOf": [
        {
          "$ref": "#/$defs/EnvelopeView"
        },
        {
          "properties": {
            "actionCount": {
              "minimum": 0,
              "type": "integer"
            },
            "connectionDefinitionId": {
              "$ref": "#/$defs/ConnectionDefinitionId"
            },
            "imageUrl": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "platform": {
              "type": "string"
            }
          },
          "required": [
            "connectionDefinitionId",
            "name",
            "platform",
            "imageUrl",
            "actionCount"
          ],
          "type": "object"
        }
      ]
    }
  }
}