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, people, and applications fit together, see Core concepts.

Prerequisites

You are logged in as the profile’s owner or a co-owner. Deciding what the public sees, and changing who has access, are theirs alone. 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.

You decide what the public sees part by part. A part is a section of the profile (Summary, Expertise, Contact, …) or a kind of file (Paper full text, CV, Grants, …). For each part the public gets None or Read. The public reading at least one part is what “published” means; the public reading nothing means the profile is unpublished, and an anonymous request for it returns 404.

In the web UI

Open Privacy from the menu under your avatar (/privacy). The same page holds the public and your API keys. Under Public, pick the profile if you own more than one (the Privacy tab of a profile opens this page with that profile picked).

1. Next to The public, click Edit. In Permissions for: The public, set each part to None or Read. The Presets beside the list fill it in one click:

   • Nothing: the public sees nothing (unpublished).
   • Basics: Summary, Expertise, Research focus, and Publication list.
   • Extended: everything except Contact, CV, Grants, Paper full text, Interview digest, and Web pages.
   • Everything: every part.

   The buttons only fill in the choices. Nothing remembers which one you pressed; the list always shows what the public actually gets.

2. Click Save. If this publishes the profile, you are asked to confirm first.

3. Click Preview as Public to see your profile exactly as a stranger gets it, or Preview as you to compare.

API keys are right below on the same page, in the same kind of list. People, teams, and apps are on each profile’s Access tab instead.

From the command line

1. Read the current list:

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

   {
     "slug": "jane-doe",
     "published": false,
     "parts": [{"id": "summary", "read": false}, {"id": "cv", "read": false}],
     "floor_reason": "You have not published this profile, so the public sees none of it. ...",
     "can_edit": true
   }

   There is one row per part this profile has. read is null for a kind of file whose files disagree (some public, some not).

2. Save the parts you want public. Parts you leave out keep what they have. When this publishes the profile, 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 PUT https://prosopia.databio.org/api/v1/manage/profiles/jane-doe/public-access \
     -d '{"parts": {"summary": "read", "expertise": "read", "focus": "read", "works": "read"},
          "confirm": "jane-doe"}'

   This writes the choices into the profile and records a consent row in profile_publications, with the change in the audit trail. No ingest path, migration, or bulk import can write that row, so a bulk import can never publish anyone.

Unpublish

Set every part to none. Withdrawing consent is never obstructed, so unpublishing needs no confirm:

curl -b "rp_session=<your-cookie>" \
  -H "Content-Type: application/json" \
  -X PUT https://prosopia.databio.org/api/v1/manage/profiles/jane-doe/public-access \
  -d '{"parts": {"summary": "none", "expertise": "none", "focus": "none", "works": "none"}}'

Unpublishing immediately purges the profile’s cached public pages. It only takes the profile off the open web. You, your co-owners and editors, the people, teams, and apps on the profile’s Access tab, the API keys their people allowed, and operators keep reading what they were allowed.

What can go wrong

• 400: publishing without confirm, or with a confirm that isn’t the slug; an unknown part; or a level other than read or none (the public never writes). Nothing is changed.
• 403: you’re an editor, an operator token, or an application. Only the owner or a co-owner, in person, may change what the public sees.

Review the history

GET /api/v1/manage/profiles/<slug>/publication shows the publication state. The owner’s view 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

Each profile has one access list, on its Access tab (/manage/<slug>/access). Add a person (by ORCID iD or email), a team, or an app, with one role:

• Reader: reads the parts you pick, beyond what the public sees.
• Editor: edits the content and pushes updates. May not publish, delete, or change the list.
• Co-owner: everything you may do except hand the profile over.

Only you and your co-owners change the list; editors can see it. People, teams, and apps can also ask for a role, and you approve or deny each request on the same tab. For every option, see How to share ownership.

Add someone

On the Access tab, type an ORCID iD or an email (or pick a team or an app), pick a role, and click Add. From the command line:

curl -b "rp_session=<your-cookie>" \
  -H "Content-Type: application/json" \
  -X POST https://prosopia.databio.org/api/v1/manage/profiles/jane-doe/access \
  -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. Naming them by email adds the account that signs in with that verified email now, or else saves a pending invite that turns into an entry the first time they sign in with it. It returns 201 Created with the entry, including its id. A reader also takes parts or a preset (basics, extended, or read_all, the default).

Ownership isn’t transferable here. A profile has exactly one owner.

List and remove

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

What can go wrong

• 400: an invalid role, parts, or preset; naming the owner; or naming more or fewer than one person, team, or app.
• 401: you’re not logged in.
• 403: you’re an editor or reader, not the owner or a co-owner, or you’re calling with an application key rather than as a person.
• 404: no such entry when removing. Also the answer for a profile you’re not allowed to see: it looks exactly like a profile that does not exist, never a 403.
• 409: the email belongs to more than one account; add them by ORCID.

Share with applications

There are two kinds, set in two places:

• Apps are the platform apps the site operator registered. You add one to a profile’s Access tab like a person: as a Reader (with the parts it may read), an Editor, or a Co-owner. An app can also ask for a role, and you approve or deny it there. Profiles made before the access list existed, and profiles nobody has claimed, list the Sponsus app as a reader of four clinical parts; you can remove it.
• API keys are keys you make yourself, for a tool you run or an agent you use. They are on your Privacy page (/privacy), under API keys.

Each key has its own list of parts, the same parts as the Privacy page. For each part it gets None, Read, or Write (Write includes Read). A key’s list covers everything your account can reach: every profile you own or have a role on, and the collections you can see. A key never gets more than you may do yourself. Which apps can see a collection is set on that collection’s Access tab.

Click Edit next to a key to open Permissions for: it, the same dialog as the public’s, with a Write column. The Presets beside the list fill it in one click: Nothing, Basics, Extended, Read all, Edit profile (write every profile section, read everything else), or Everything (write every part in the list, and turn on Replace whole profiles: total control). As for the public, the buttons only fill in the choices, and each list shows what the key actually gets, for example “Reads all but Grants, CV · Writes Summary”.

A few rules always hold:

• An app or key never reads less than the public. What the public sees is on the open web anyway, so an app with no entry “Reads only what the public sees”.
• No app or key can publish, unpublish, delete a profile, or give access. Those are yours alone.
• Every part can be written. A section changes through the edit routes, a file (a paper summary, the CV, grants, web pages) through a push such as rp push --only <file> --mode merge. An app writes as an editor or co-owner; a key writes only the parts its list sets to Write, and a push lands only if every part it changes is Write. Otherwise nothing changes and the answer names the missing parts.
• A push by anyone but you or a co-owner never changes a field you edited by hand.

Read-only is the default worth reaching for. A new API key reads everything and writes nothing. 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 nothing more. Set a part to Write only for a tool that is meant to edit, and only the parts you mean it to edit. For an app, a Reader entry is the same choice.

API keys have one extra switch, Replace whole profiles. It lets a key overwrite a whole profile at once, every part together, including what the public sees and anything no part covers (such as how the profile was made). Everything turns it on. The login rp login makes has it on. An app gets the same power only as a Co-owner.

An API key is safe to paste into somebody else’s application because it is worth nothing beyond your account: it reaches what you can reach, and on every other profile in the registry it sees exactly what an anonymous visitor sees.

For the endpoints behind these lists, see the API reference.