{
  "openapi": "3.1.0",
  "info": {
    "title": "Hybrid ID consented shared profile",
    "version": "1.0.0",
    "description": "App-bound, subject-bound presentation with independent private-display and public-redistribution consent. See externalDocs and release record for deployment status."
  },
  "servers": [
    {
      "url": "https://auth.hybrid-id.com"
    }
  ],
  "externalDocs": {
    "url": "https://hybrid-id.com/integrations/shared-profile.md"
  },
  "paths": {
    "/profile/shared": {
      "post": {
        "operationId": "sharedProfile",
        "summary": "Read approved profile fields, refresh public sharing or retrieve current avatar bytes",
        "description": "Server-to-server JSON only, <=8192 bytes. HTTP Basic is always required; user access token or publication ID is supplied in JSON. Each field requires the corresponding separately approved scope. Ordinary openid profile is insufficient. No browser Origin, query parameters or extra JSON fields.",
        "security": [
          {
            "clientBasic": []
          }
        ],
        "x-consent-scopes": {
          "profile:display": [
            "display_name",
            "language"
          ],
          "profile:avatar:display": [
            "avatar"
          ],
          "profile:location:display": [
            "location"
          ],
          "profile:publish": [
            "display_name",
            "language"
          ],
          "profile:avatar:publish": [
            "avatar"
          ],
          "profile:location:publish": [
            "location"
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "subject",
                      "purpose",
                      "access_token",
                      "fields"
                    ],
                    "properties": {
                      "operation": {
                        "const": "read"
                      },
                      "subject": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "purpose": {
                        "type": "string",
                        "enum": [
                          "private",
                          "public"
                        ]
                      },
                      "access_token": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 4096
                      },
                      "fields": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 4,
                        "uniqueItems": true,
                        "items": {
                          "type": "string",
                          "enum": [
                            "display_name",
                            "language",
                            "avatar",
                            "location"
                          ]
                        }
                      }
                    }
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "subject",
                      "purpose",
                      "publication_id",
                      "fields"
                    ],
                    "properties": {
                      "operation": {
                        "const": "refresh"
                      },
                      "subject": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "purpose": {
                        "const": "public"
                      },
                      "publication_id": {
                        "type": "string",
                        "pattern": "^hps_[A-Za-z0-9_-]{43}$"
                      },
                      "fields": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 4,
                        "uniqueItems": true,
                        "items": {
                          "type": "string",
                          "enum": [
                            "display_name",
                            "language",
                            "avatar",
                            "location"
                          ]
                        }
                      }
                    }
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "subject",
                      "purpose",
                      "access_token",
                      "version"
                    ],
                    "properties": {
                      "operation": {
                        "const": "avatar"
                      },
                      "subject": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "purpose": {
                        "type": "string",
                        "enum": [
                          "private",
                          "public"
                        ]
                      },
                      "access_token": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 4096
                      },
                      "version": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{64}$"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "subject",
                      "purpose",
                      "publication_id",
                      "version"
                    ],
                    "properties": {
                      "operation": {
                        "const": "avatar"
                      },
                      "subject": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "purpose": {
                        "const": "public"
                      },
                      "publication_id": {
                        "type": "string",
                        "pattern": "^hps_[A-Za-z0-9_-]{43}$"
                      },
                      "version": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{64}$"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "privateRead": {
                  "value": {
                    "operation": "read",
                    "subject": "validated-pairwise-sub",
                    "purpose": "private",
                    "access_token": "server-only-oidc-token",
                    "fields": [
                      "display_name",
                      "avatar"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "400": {
            "description": "invalid_request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "const": "invalid_request"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "invalid_client",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "const": "invalid_client"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "access_denied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "const": "access_denied"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "avatar_absent",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "const": "avatar_absent"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "method_not_allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "const": "method_not_allowed"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "version_changed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "const": "version_changed"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "request_too_large",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "const": "request_too_large"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "const": "rate_limited"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string",
                  "const": "60"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "const": "temporarily_unavailable"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "200": {
            "description": "Profile metadata or authorized avatar bytes. No-store; ETag never bypasses authorization. All times Unix seconds.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Hybrid-Profile-Valid-Until": {
                "description": "Avatar response permission snapshot expiry.",
                "schema": {
                  "type": "string",
                  "pattern": "^[0-9]+$"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SharedProfile"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "maxLength": 400000
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "clientBasic": {
        "type": "http",
        "scheme": "basic",
        "description": "Registered confidential app client ID and current secret. OIDC/publication proof is separately required in the request."
      }
    },
    "schemas": {
      "SharedProfile": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "issuer",
          "client_id",
          "subject",
          "purpose",
          "fields",
          "version",
          "observed_at",
          "valid_until"
        ],
        "properties": {
          "schema": {
            "const": "hybrid.shared-profile.v1"
          },
          "issuer": {
            "type": "string",
            "format": "uri"
          },
          "client_id": {
            "type": "string"
          },
          "subject": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "purpose": {
            "type": "string",
            "enum": [
              "private",
              "public"
            ]
          },
          "fields": {
            "type": "object",
            "additionalProperties": false,
            "required": [],
            "properties": {
              "display_name": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 201
              },
              "language": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 16
              },
              "location": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 160
              }
            }
          },
          "version": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "observed_at": {
            "type": "integer",
            "minimum": 0
          },
          "valid_until": {
            "type": "integer",
            "minimum": 0
          },
          "avatar": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "state",
                  "version"
                ],
                "properties": {
                  "state": {
                    "const": "absent"
                  },
                  "version": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                  }
                }
              },
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "state",
                  "version",
                  "content_type",
                  "size_bytes",
                  "width",
                  "height"
                ],
                "properties": {
                  "state": {
                    "const": "present"
                  },
                  "version": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                  },
                  "content_type": {
                    "const": "image/png"
                  },
                  "size_bytes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 400000
                  },
                  "width": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 300
                  },
                  "height": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 300
                  }
                }
              }
            ]
          },
          "publication_id": {
            "type": "string",
            "pattern": "^hps_[A-Za-z0-9_-]{43}$"
          },
          "publication_expires_at": {
            "type": "integer",
            "minimum": 0
          }
        }
      }
    }
  }
}
