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.

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:

   curl -b "rp_session=<your-cookie>" \
     -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:

   curl -b "rp_session=<your-cookie>" \
     https://prosopia.databio.org/api/manage/profiles/jane-doe/publication

   {
     "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:

   curl -b "rp_session=<your-cookie>" \
     -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:

curl -b "rp_session=<your-cookie>" \
  -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:

   curl -b "rp_session=<your-cookie>" \
     -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

curl -b "rp_session=<your-cookie>" \
  -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

curl -b "rp_session=<your-cookie>" \
  https://prosopia.databio.org/api/manage/profiles/jane-doe/managers
curl -b "rp_session=<your-cookie>" \
  -X DELETE https://prosopia.databio.org/api/manage/profiles/jane-doe/managers/7

curl -b "rp_session=<your-cookie>" https://prosopia.databio.org/api/manage/permissions
curl -b "rp_session=<your-cookie>" \
  -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.