# How to share ownership of a profile

There are two different things you can share, and they live in two places:

- **Managing this profile** — let another *person* co-own or edit one
  profile. This is per profile: a manager row.
- **Reading everything you hold** — let a person or an application read (or
  write) your data as a whole: every profile you own and every lens you have
  written. This is per *person*, not per profile: a permission on you.

For how these relate to identity and the one owner per profile, see
[Core concepts](/prosopia/concepts.md).

## Prerequisites

- You are logged in with ORCID and own the profile.
- You know the profile's slug, and the ORCID iD (for a person) or consumer
  id/name (for an application).

## Add a co-manager

1. Post the manager. `role` is `co-owner` (everything you may do except
   transfer ownership) or `editor` (rewrite the document; may not publish,
   delete, or manage access):

    ```bash
    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 do
    not need an account first. It takes effect when they next log in.

2. Confirm. It returns `201 Created`:

    ```json
    {
      "id": 7,
      "profile_rid": "0000-0002-1825-0097",
      "profile_slug": "jane-doe",
      "user_id": 42,
      "orcid": "0000-0002-7115-4020",
      "role": "editor",
      "granted_by": 1
    }
    ```

Ownership is not transferable here. A profile has exactly one owner.

### List managers

The owner or any manager may read the list:

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

### Remove a manager

Delete by the manager `id` from the list. The owner cannot be removed:

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

## Give a person or an application access to your data

A permission is all-or-nothing: whoever holds it reads everything you own —
this profile, including fields marked restricted, and the lenses you wrote —
whether or not the profile is published. `write` additionally lets them
rewrite your profiles. There is no lab-only permission.

1. Post the permission. `principal_kind` is `user` (a person, by ORCID) or
   `consumer` (an application, by id or name); `grant_type` is `read` or
   `write`:

    ```bash
    curl -b "rp_session=<your-cookie>" \
      -H "Content-Type: application/json" \
      -X POST https://prosopia.databio.org/api/manage/permissions \
      -d '{"principal_kind": "consumer", "principal_ref": "winnow", "grant_type": "read"}'
    ```

2. Confirm. It returns `201 Created` with the permission, including its `id`.

The Access tab on your profile does the same thing for applications with one
button per app.

### List and revoke permissions

```bash
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 are not logged in.
- **`403`**: you are not the owner (managers), or you are calling with an
  application key rather than as a person (permissions).
- **`404`**: no such consumer, or no such manager/permission when revoking.

## Letting one tool act for you

To let a specific tool edit on your behalf with scoped, auditable access, mint a
dedicated agent key rather than giving a broad application a `write`
permission. That path issues the permission automatically and lets you choose
exactly which fields it may write.