# Consented shared profiles

Hybrid ID supplies canonical, self-declared identity presentation to registered
confidential relying applications. This is not KYC, proof of a legal name or a
verified address. Cortex owns its professional headline, biography, cover image,
roles, posts and other application-specific presentation. Do not overwrite these
with Hybrid ID fields. Cortex-uploaded photos remain Cortex-owned unless the user
explicitly chooses a Hybrid ID synchronized photo.

Deployment and acceptance evidence: release record (contact the integration team).
[Integration manifest](https://hybrid-id.com/integrations/manifest.json) ·
[OpenAPI](https://hybrid-id.com/integrations/shared-profile.openapi.json) ·
[General integration guide](https://hybrid-id.com/developers/integration#shared-profile).

## Permissions

Request only the scopes needed through the existing Authorization Code + PKCE S256
flow. These optional scopes are available to registered confidential applications;
allowing an app to request them does not approve any user. A user explicitly approves
new permissions on Hybrid ID. Basic `openid profile` never grants this endpoint,
avatar synchronization or public photo permission.

| Scope | Approved use | Fields |
| --- | --- | --- |
| `profile:display` | Private signed-in presentation | `display_name`, `language` |
| `profile:avatar:display` | Private signed-in photo | `avatar` |
| `profile:location:display` | Private signed-in location | `location` |
| `profile:publish` | Public profiles, discovery, posts and comments | `display_name`, `language` |
| `profile:avatar:publish` | Public photo in those surfaces | `avatar` |
| `profile:location:publish` | Public location in those surfaces | `location` |

Private and public scopes are independent. Public permission does not substitute for
private permission, and vice versa. Displaying a photo to other people in a profile,
post or comment requires public permission even when those viewers have signed in.
The `fields` list further minimizes each response. A requested field with no value
is `null`; unrequested fields are omitted. No email, native account ID, date of birth,
KYC location, passport or other evidence is returned. Location is an optional city or
region entered by its owner in Hybrid ID; never infer it from IP or verification data.

## Existing sessions and additional consent

Use a new authorization request for the same client, exact callback and desired
scopes, with fresh state, nonce and PKCE. Do not set `prompt=login` just to request
permission. An active Hybrid ID SSO session is reused; the user sees consent for
additional scopes. An expired session or security policy can still require login.
A silent `prompt=none` request cannot approve new permissions: handle the returned
OIDC interaction/consent error by offering a normal interactive authorization.
Keep the application's current session while this consent flow runs, and validate
that the callback's `(issuer, sub)` matches its intended account before attaching
any data. An expired access token requires a new authorized token; this integration
does not add a refresh-token grant.

## Endpoint and authentication

`POST https://auth.hybrid-id.com/profile/shared`

Server-to-server only. Send `Content-Type: application/json` and HTTP Basic with
registered `client_id:client_secret`. JSON is limited to 8192 bytes. Browser Origin,
query parameters, extra JSON fields, duplicate field names in `fields`, arbitrary
image URLs and caller-selected native IDs are not accepted. Keep credentials,
access tokens and publication IDs out of URLs, browser code and logs. All responses
are `Cache-Control: private, no-store` (errors also no-store); no public CDN caching.
The subject is the validated OIDC **pairwise `sub` for this app**, not an email or a
native Hybrid account identifier. Check issuer, audience, signature and nonce first.

Initial read, with private scopes approved:

```json
{
  "operation": "read",
  "subject": "<validated pairwise sub>",
  "purpose": "private",
  "access_token": "<current app-bound OIDC access token>",
  "fields": ["display_name", "language", "avatar"]
}
```

Example response (timestamps illustrative Unix seconds):

```json
{
  "schema": "hybrid.shared-profile.v1",
  "issuer": "https://auth.hybrid-id.com",
  "client_id": "<your registered client ID>",
  "subject": "<validated pairwise sub>",
  "purpose": "private",
  "fields": {"display_name": "Alex Morgan", "language": "en"},
  "version": "<64 lowercase hex characters>",
  "observed_at": 1791324000,
  "valid_until": 1791324060,
  "avatar": {
    "state": "present",
    "version": "<64 lowercase hex characters>",
    "content_type": "image/png",
    "size_bytes": 8450,
    "width": 300,
    "height": 300
  }
}
```

Fetch bytes with a **separate** request using the exact avatar version:

```json
{
  "operation": "avatar",
  "subject": "<same pairwise sub>",
  "purpose": "private",
  "access_token": "<current app-bound OIDC access token>",
  "version": "<avatar.version>"
}
```

Success is `200 image/png`, at most 400,000 bytes and at most 300 × 300 pixels.
Metadata is removed by the canonical image upload path (PNG/JPEG/WebP input,
500,000 bytes, at most four megapixels). The image response has `ETag` equal to its
quoted version and `X-Hybrid-Profile-Valid-Until` (Unix seconds). This endpoint
returns controlled **bytes**, not a reusable public URL or base64 inside JSON.
Version identifiers are opaque and bound to app, account, purpose and consent.
ETag is for detecting changes: the service does not return an unauthenticated 304;
every request rechecks permission. Do not use a native account-session avatar URL.

## Public sharing after sign-out

With the relevant `*:publish` scopes explicitly approved, make the initial `read`
with `purpose: "public"` and a current access token. The result also includes
`publication_id` and `publication_expires_at`. Save these server-side against this
exact issuer/client/subject. This is limited permission to refresh those public
fields; it is **not authentication**, account access, a company role or execution
authority. It expires with its recorded approval (at most one year at creation)
and cannot be renewed silently beyond that receipt's expiry.

After sign-out the backend can continue refreshing the approved public presentation
without storing or impersonating a private Hybrid browser session:

```json
{
  "operation": "refresh",
  "subject": "<same pairwise sub>",
  "purpose": "public",
  "publication_id": "hps_<opaque reference>",
  "fields": ["display_name", "language", "avatar"]
}
```

Use the same publication ID instead of `access_token` for `operation: "avatar"`,
`purpose: "public"`, and its current avatar version. HTTP Basic is still required.
Only fields included in the original publication can be refreshed. New fields need
a fresh authorized read; new scopes need additional user consent. Key rotation
requires the new client secret; the stable subject and publication do not change.
Client disablement, changed client binding, native account deactivation, expired
publication or withdrawn approval deny further disclosure. Re-approval after
withdrawal never revives an old publication ID.

## Updates, removal and outages

While displaying synchronized fields, validate at or before `valid_until` (at most
60 seconds). An application may coalesce backend checks per account/purpose for
that period. It may stop checking when nothing is displayed, but must revalidate
before showing the fields again. There are no shared-profile webhooks in v1.

- A successful new version replaces only the synchronized fields. Bind any async
  response to the original account and discard it if the viewer/account changed.
- `null` clears the corresponding synchronized text. `avatar.state: "absent"`
  means no current photo, including deletion: remove the synchronized image.
- `404 avatar_absent` has the same removal meaning. `409 version_changed` means
  reread metadata and request the new image; never substitute a different account's
  cached image. Photos can change between metadata and byte retrieval.
- `403 access_denied` means permission cannot currently be established. Immediately
  stop using and remove the synchronized fields/image and invalidate that sharing
  reference; offer fresh consent when appropriate. Never fall back to private data
  for a public surface.
- `503 temporarily_unavailable` and network errors are **not deletion**. Do not
  overwrite canonical or independently uploaded Cortex data. Hide synchronized
  presentation once its permission snapshot expires, retain only a non-displayable
  pending refresh state, and retry with backoff. A neutral placeholder is suitable.
- `401 invalid_client` requires backend credential/configuration attention; stop
  displaying expired synchronized data. `429 rate_limited` includes `Retry-After: 60`.
  Normal capacity is 120 requests/minute per app+subject; the existing exact-owner
  unlimited entitlement is preserved. It does not bypass consent or account checks.

Partition application caches by **issuer + client ID + subject + purpose + field
version**, never by email, filename or a global `/avatar` cache key. A private image
proxy must enforce its current application account session and use `private,
no-store`; do not allow a former account's in-flight image response to populate a
new account. Public rendering must check its publication permission lease, use the
same full partition, and avoid immutable/public-CDN caches. Clear object URLs,
component state and private cache entries on sign-out/account switch. No expiry can
recall copies already saved by external viewers, screenshots or independent archives.

Owners can remove their photo/location in **Profile data**, or withdraw the app's
whole approval in **Access requests → Connected applications**. Delivery is denied
immediately after withdrawal; participating applications must stop display within
the 60-second lease. Individual per-scope withdrawal and push notifications are
not implemented in v1. Application-specific headline/bio/cover remain separate.

## Errors and acceptance

Errors are JSON `{ "error": "<code>", "message": "<human-readable text>" }`.
Status/code pairs: 400 `invalid_request`, 401 `invalid_client`, 403 `access_denied`,
404 `avatar_absent`, 405 `method_not_allowed`, 409 `version_changed`,
413 `request_too_large`, 429 `rate_limited`, 503 `temporarily_unavailable`.
Never interpret a generic non-200 as photo deletion.

Provider and native acceptance cover app/account isolation, scope separation,
source lifecycle, image changes/deletion, consent withdrawal/re-approval, key
rotation, outages and rechecks during retrieval. The actual OIDC flow verifies
additional consent with an existing SSO session. See the linked release record
for deployment evidence and limits. Cortex must still implement its own sync and
cache-isolation tests before enabling automatic photos in its UI.
