# Getting started

In this tutorial you will sign in to Prosopia with your ORCID, claim the profile
that already carries your ORCID iD, make your first edit to it, and then publish
it to the open web. Prosopia keeps two acts separate: **claiming** (taking
ownership) and **publishing** (agreeing to be seen). By the end you will have
done both, and you will have seen a profile stay private until you publish it,
even after you own it.

This tutorial assumes you have an [ORCID iD](https://orcid.org) and that a
profile carrying that iD already exists in Prosopia (the build pipeline creates
these). If no profile matches your iD yet, follow
[Create a profile](/prosopia/how-to/create-a-profile.md) instead, then return here to
publish it.

Everything below happens in the web UI at
[prosopia.databio.org](https://prosopia.databio.org). Each step calls an HTTP
endpoint under the hood. The endpoints are named here so you can find them in
the [API reference](/prosopia/reference/api.md).

## Step 1: Sign in with ORCID

Open [prosopia.databio.org](https://prosopia.databio.org) and choose to sign in.
Prosopia redirects you to ORCID's authorization page (`GET /api/manage/login`).
After you approve, ORCID sends you back and Prosopia mints a signed session
cookie (`GET /api/manage/callback`).

You should now see your name in the interface. Behind the page, the app has read
`GET /api/manage/session`, which reports:

```json
{
  "authenticated": true,
  "user": { "orcid": "0000-0002-1825-0097", "name": "Jane Doe" },
  "owned": [],
  "claimable": ["jane-doe"],
  "creatable": false
}
```

The profile whose `rid` equals your ORCID iD appears under **claimable**. You do
not own it yet, but Prosopia can see it is yours to claim.

## Step 2: Claim your profile

On your account screen (`#/me`), find the profile listed as claimable and claim
it. This sends `POST /api/manage/claims` with the profile's slug.

Prosopia verifies the claim entirely on the server. It checks that your session's
authenticated ORCID iD equals the profile's `rid`, and that nobody owns it yet.
Because the `rid` *is* the ORCID, the match is self-verifying. There is no
separate "prove you own this" step and no operator approval.

The response seeds your owner grant and returns your owned profiles:

```json
{
  "slug": "jane-doe",
  "rid": "0000-0002-1825-0097",
  "owned": [
    { "slug": "jane-doe", "rid": "0000-0002-1825-0097",
      "visibility": "public", "published": false }
  ]
}
```

Note the `published: false` field. You now **own** the profile, and it is still
**not published**. Claiming and publishing are two different acts; you have done
only the first.

## Step 3: Confirm it is still private

Before editing, see what a stranger sees. Open the profile's public URL in a
private browser window (no session cookie), or ask for its publication state on
your owner screen (`GET /api/manage/profiles/jane-doe/publication`):

```json
{
  "slug": "jane-doe",
  "published": false,
  "profile_visibility": "public",
  "floor": "internal",
  "floor_reason": "You have not published this profile. Claiming a profile does not publish it; publishing is a separate decision you make, and can undo. Until you do, it stays lab-visible.",
  "visible_to_anonymous": false
}
```

The document itself declares `visibility: public`, but the profile is capped at
`internal` because you have not published it. `visible_to_anonymous` is `false`,
so a stranger sees nothing. This cap is the point: owning a profile does not put
it on the open web.

## Step 4: Make your first edit

Open the editing screen (`#/edit`) and change something, such as your one-line
summary. Saving it sends `PATCH /api/v1/profiles/jane-doe/metadata`, one of the
SDK's edit endpoints. The owner grant you hold authorizes the request, not an
operator token.

The change is live immediately for you and anyone you have granted access. It is
still invisible to strangers, because you still have not published.

## Step 5: Publish

Now agree to be seen. On your owner screen, publish the profile. This sends:

```
POST /api/manage/profiles/jane-doe/publication
{
  "published": true,
  "confirm": "jane-doe"
}
```

The `confirm` value must equal the profile's slug. Prosopia refuses an
accidental publish the same way a delete flow asks you to type a name. Only you,
signed in as the person the profile describes, can do this. An editor you invited
cannot publish, and neither can an application holding a key.

The response reports the composed truth:

```json
{
  "published": true,
  "profile_visibility": "public",
  "floor": null,
  "visible_to_anonymous": true,
  "changed": true
}
```

The floor is gone. Reopen the public URL in a private window. Your profile is now
served to anonymous readers.

## Step 6: See that you can take it back

Publishing is revocable. Unpublish the profile with the same endpoint and
`"published": false`. No `confirm` is required, because nothing may obstruct
withdrawing consent. The floor returns to `internal`, and a stranger stops seeing
the profile on the next request. Every publish and unpublish you have done is
kept in an append-only history on your owner screen.

## Summary

- Signing in with **ORCID** mints a signed session cookie; your authenticated
  ORCID iD is your identity.
- **Claiming** a profile whose `rid` equals your ORCID iD is self-verifying and
  gives you the **owner** grant, but it does not publish anything.
- A profile you own is capped at **`internal`** until you publish it, whatever
  its document declares; a stranger sees nothing.
- **Publishing** is a separate, deliberate, revocable act that only the person
  the profile describes can perform.

## Next steps

- [Core concepts](/prosopia/concepts.md): identity, ownership, and visibility in depth.
- [Share ownership](/prosopia/how-to/share-ownership.md): grant an editor or viewer role
  to a colleague.
- [Build a profile](/prosopia/how-to/build-on-demand.md): fill in a shell profile with
  papers and an expertise narrative, using the `researcher-profile` skill.