# How to share your profile Prosopia gives you control over who sees your profile: the general public, specific people, or specific applications. Each is a separate control, and you can change any of them at any time. For how publication, grants, and visibility tiers work together, see [Core concepts](/prosopia/concepts.md). ## Prerequisites You are logged in with ORCID and hold the **owner** grant on the profile. Publishing, granting, and revoking are all owner-only actions — an editor, an operator token, or an application key cannot do them. The examples below use `curl`, but everything here can also be done from the web UI. ## Share publicly (publish) Publishing puts your profile on the open web. Claiming or creating a profile does not publish it — that's a separate, deliberate step, and it's the **owner's** decision, even if the owner isn't the person the profile describes. Every publish and unpublish is written to an append-only audit trail. Until you publish, a profile is capped at `internal` regardless of what the document itself declares, so an anonymous request for it returns `404`. Publishing lifts that cap; the document's own visibility tier then decides what each caller actually sees. ### Publish 1. Post the publication decision. `confirm` must equal the profile's slug, the same guard used for deletion: ```bash curl -b "rp_session=" \ -H "Content-Type: application/json" \ -X POST https://prosopia.databio.org/api/manage/profiles/jane-doe/publication \ -d '{"published": true, "confirm": "jane-doe"}' ``` This records a consent row in `profile_publications` and writes the transition to the audit trail. No ingest path, migration, or bulk import can write that row, so a bulk import can never publish anyone. 2. Check that a stranger can actually see it. Publishing feeds the tier authority, but the profile's own document tier still applies: ```bash curl -b "rp_session=" \ https://prosopia.databio.org/api/manage/profiles/jane-doe/publication ``` ```json { "slug": "jane-doe", "published": true, "profile_visibility": "internal", "floor": null, "visible_to_anonymous": false, "still_visible_to": ["lab consumers", "you and anyone you granted", "operators"] } ``` Here `visible_to_anonymous` is `false` because the document declares `internal`. The profile is published but still shows a stranger nothing — this is the half-published state. 3. Resolve the half-published state in one act. A newly created profile starts at `internal`. To publish and make it publicly visible together, set `profile_visibility` in the same request: ```bash curl -b "rp_session=" \ -H "Content-Type: application/json" \ -X POST https://prosopia.databio.org/api/manage/profiles/jane-doe/publication \ -d '{"published": true, "confirm": "jane-doe", "profile_visibility": "public"}' ``` ### Unpublish (revoke) Withdrawing consent is never obstructed, so unpublishing needs no `confirm`: ```bash curl -b "rp_session=" \ -H "Content-Type: application/json" \ -X POST https://prosopia.databio.org/api/manage/profiles/jane-doe/publication \ -d '{"published": false}' ``` Unpublishing sets a floor of `internal` and immediately purges the profile's cached public pages. It's a narrowing, not a blackout: as `still_visible_to` shows, lab consumers, you and anyone you granted, and operators keep reading the profile, as they always could. To withhold it from lab consumers too, set the document to `restricted` instead — a different control. ### What can go wrong - **`400`**: publishing without `confirm`, or with a `confirm` that isn't the slug. Nothing is recorded. - **`403`**: you're an editor, an operator token, or an application. Only the owner, in person, may publish or unpublish. ### Review the history The owner's view of the publication state includes `published_by`, `revoked_by`, and the full `history` of every publish and unpublish, each with its actor and timestamp. An editor may read the state but not those identities. ## Share with specific people Two different things, in two places: - **Let someone manage this profile.** Add them as a **co-owner** (everything you may do except transfer ownership) or an **editor** (rewrite the document; may not publish, delete, or manage access). This is per profile. - **Let someone read everything you hold.** Give them a **permission** on you: `read` sees every profile you own and every lens you wrote, in full, published or not; `write` may also rewrite your profiles. This is per person, not per profile, and all-or-nothing. ### Add a manager 1. Post the manager, by ORCID. `role` is `co-owner` or `editor`: ```bash curl -b "rp_session=" \ -H "Content-Type: application/json" \ -X POST https://prosopia.databio.org/api/manage/profiles/jane-doe/managers \ -d '{"orcid": "0000-0002-7115-4020", "role": "editor"}' ``` Naming a person by ORCID creates or reuses their user record, so they don't need an account first. It takes effect when they next log in. 2. Confirm. It returns `201 Created` with the manager row, including its `id`. Ownership isn't transferable here. A profile has exactly one owner, and publishing, deleting, and managing access stay with the owner (and any co-owner). ### Give someone a permission ```bash curl -b "rp_session=" \ -H "Content-Type: application/json" \ -X POST https://prosopia.databio.org/api/manage/permissions \ -d '{"principal_kind": "user", "principal_ref": "0000-0002-7115-4020", "grant_type": "read"}' ``` `principal_kind` is `user` (a person, by ORCID) or `consumer` (an application, by id or name). It returns `201 Created` with the permission, including its `id`. ### List and revoke ```bash curl -b "rp_session=" \ https://prosopia.databio.org/api/manage/profiles/jane-doe/managers curl -b "rp_session=" \ -X DELETE https://prosopia.databio.org/api/manage/profiles/jane-doe/managers/7 curl -b "rp_session=" https://prosopia.databio.org/api/manage/permissions curl -b "rp_session=" \ -X DELETE https://prosopia.databio.org/api/manage/permissions/7 ``` ### What can go wrong - **`400`**: an invalid role or grant type, or naming yourself. - **`401`**: you're not logged in. - **`403`**: you're not the owner (managers), or you're calling with an application key rather than as a person (permissions). - **`404`**: no such consumer, or no such manager/permission when revoking. ## Share with applications To let a specific application read or edit your profile, mint a dedicated agent key rather than giving a broad application a `write` permission. You choose exactly what the application may do, and each application you connect gets its own key, which you can revoke anytime. **Read-only is the default worth reaching for.** An application that only wants to *use* your profile -- a paper recommender seeding itself from your publication list, a CV builder, an agent answering questions about your work -- needs `read` and nothing else. That key reads your profile in full, including the lab-only and owner-only parts, and can change nothing. Tick a write scope (`profile:metadata`, `profile:narrative`, ...) only for a tool that is meant to edit, and only the fields you mean it to edit. An agent key is safe to paste into somebody else's application because it is worth nothing anywhere else: it reaches the one profile you minted it against, and on every other profile in the registry it sees exactly what an anonymous visitor sees. For key issuance and scoping, see the [API reference](/prosopia/reference/api.md).