Managing Access to a Collection

This page provides the practical instructions on how to

• create a collection,
• transfer or delegate management of a collection,
• assign groups with read or write access to a collection,
• enable and create shares of a collection, and so on.

Every task here is written for the origin’s web interface, because that is the one place all of it can be done.

As described in the overview,

• A collection is a prefix inside a namespace your origin already exports, together with the groups allowed to read or write it.
• A share is a child collection an ordinary user creates to hand part of their own access to someone else.

The lab in the examples

To help contextualize the instructions, we’ll include snippets from the overview example.

Riptide University runs a Pelican origin in front of its research storage, already exporting the prefix /riptide-university. The Reyes Lab studies nearshore currents, and has just come back from a field season with several terabytes of instrument data that its collaborators need to reach.

Throughout this guide, the lab’s collection will be created, handed to the people who run it, and opened up to students — with one student passing part of that access on to classmates outside the lab. Here is a summary of the roles of the lab members and the permissions they’ll be given.

Before you start

You need an Origin with an exported namespace. A collection cannot be created if there is not a corresponding exported namespace.

Riptide University’s storage is exported at /riptide-university long before Brian touches the Collections page.

Create a collection

Requires: You must be a member of server.collection_admin or server.admin — see Collection administration.

Dr. Reyes emails Research Computing: several new students have joined her lab, and she wants to give them access to her data on the department storage. To reduce the back-and-forth, she wants to give her lab manager the ability to manage her lab’s data access.

Sysadmin Brian picks up the ticket. The storage is already exported at /riptide-university, so there is no new hardware and no new export to arrange — what the lab actually needs is a collection: a named prefix with an owner and a list of who may read and write it.

The ONBOARD COLLECTION form does the whole thing in one pass: the collection, its owner, and its three groups.

1. In the Origin web interface, open Collections in the left sidebar.

2. Click ONBOARD COLLECTION.

3. Under Collection, fill in:

   • Name — a short human-readable name.
   • Exported prefix — pick the exported prefix from the dropdown and type the rest of the path in the box beside it. The full path is shown back as you type. If only one namespace is served from this origin you won’t have a dropdown.
   • Description and Visibility (Private or Public).

   Brian names it Reyes Lab, picks the /riptide-university namespace from the dropdown and types reyes-lab beside it, describes it as “Nearshore current data, Reyes Lab”, and leaves it Private.

4. Under Ownership, choose who owns the collection. The default is the creator of the collection (you); use Pick an existing user to name them, Create a new user if they have no account yet, or Send an ownership invite to mint a link they redeem themselves. Pick an existing user and Create a new user are enabled only if you also hold server.user_admin; a plain collection administrator has the default and the invite.

   Dr. Reyes has never signed in to the origin, so Brian reaches for an ownership invite — see Transfer ownership of a collection.

5. Under Access Control, fill in the three group rows — the admin row becomes the collection’s admin group, the write row and the read row become access grants. Each row can either create a fresh group or attach one that already exists.

   Brian does not know the groups that will want to access collections, so he skips these assignments, letting the Reyes lab manage that after he passes it on.

6. Click ONBOARD COLLECTION at the bottom of the form.

One form, and Brian is done: the lab now runs its own access control, and Research Computing is out of the loop for everything that follows.

Delegate day-to-day management to an admin group

Requires: You are the collection’s owner, an existing admin-group member, or server.collection_admin — see Collection administration.

Dr. Reyes spends six weeks a year in the field without internet access to manage data access. She stays the owner — the collection is the lab’s — but puts Christina in the admin group reyes_admins, so her lab manager can grant and revoke on her behalf.

Admin-group members can

• edit the collection’s name, description,
• change the visibility and sharing setting,
• read and write its metadata,
• grant and revoke access, and
• reassign the admin group.

They cannot transfer ownership and they cannot delete the collection — both stay with the owner.

1. Open the collection’s Edit collection page.
2. In the Ownership panel, use the Admin group (optional) picker to select the group.
3. Click SAVE CHANGES.

Dr. Reyes picks reyes_admins, and from then on Christina handles the lab’s groups and grants.

Clearing the picker removes the admin group. Once one is set, a Manage admin group → link appears beside it so you can jump straight to that group’s membership page.

Grant read or write access to a group

Requires: You are a member of the collection’s admin group, the collection’s owner, or server.collection_admin — a write grant is not enough to change who else has access. See Collection administration.

Christina has set up the lab’s two working groups: reyes_researchers, for the people who collect and process data, and reyes_students, for the people who only analyze it.

Grants are written against groups. To give one person access, put them in a group. Any signed-in user can create a group; see Create a group.

1. Open Collections, find the collection, and click the Edit collection (pencil) icon on its row.
2. Scroll to Access groups.
3. In Add group, pick the group.
4. Set Role to Read or Write.
5. Click ADD.
6. Repeat for each further group you want to grant.

Christina adds reyes_researchers with Role Write, then reyes_students with Role Read.

Existing grants are listed above the picker with their group name; the trash icon beside a row revokes the grant.

Grant access to all authenticated users

Sometimes the right audience for a collection is everyone with an account on the Origin, not any one group. For that, the Add group picker offers a virtual group named All authenticated users at the top of its list. Granting it a role gives that role to every signed-in user, regardless of which groups they belong to.

Once the deployment data is cleaned up, Dr. Reyes wants anyone in the department to be able to read it. Rather than chase down every departmental group, Christina grants All authenticated users Read. The reyes_researchers grant stays in place, so the lab keeps write.

1. Open Collections, find the collection, and click the Edit collection (pencil) icon on its row.
2. Scroll to Access groups.
3. In Add group, pick All authenticated users.
4. Set Role to Read or Write.
5. Click ADD.

The grant appears in the list like any other row and is revoked the same way. On the command line and in the API, this virtual group is spelled @authenticated; see Doing this from the command line or the API.

Turn on sharing

Requires: You are the collection’s owner, an admin-group member, or server.collection_admin — see Collection administration.

Andrew wants to share part of the lab’s data for a class project. Christina has set aside some example data under /riptide-university/reyes-lab/andrews-project, but wants Andrew to manage who can read the data, without granting his classmates access to the whole reyes-lab namespace.

Shares are off by default. Turning them on lets anyone who holds read on the collection delegate part of that access onward. It creates nothing by itself; it only makes share creation reachable for the collection’s readers.

1. Open the collection’s Edit collection page.
2. Under Details, switch on Allow users to create shares.
3. Click SAVE CHANGES.

Christina turns on the sharing setting, so that Andrew can create a “share” that his classmates can access under his account.

A share versus a collection

While a share is technically a type of collection, it’s important to understand how they are different.

• The creator of a share is the sole owner of the share. Only the owner of the share can manage its access.

• A share binds data to its owner. That is, objects reached via a share are served as if the owner themselves were accessing the data.

Altogether, this means that

• The collection’s admin group cannot manage who has access to a share; it controls only what the share’s owner has access to.
• Objects in a share can only be reached if the share’s owner still has access to the parent collection (this is checked for every issuance).
• If the owner of the share has their access revoked (or sharing is disabled in the collection settings), then the objects can no longer be accessed via the share.
• Someone with access to a share cannot further extend access to someone else.

A share should be used only when data access relies on the “authority” of a single individual, i.e., the share owner.

A collection is a better choice if:

• data access should be independent of any individual’s access to the namespace, or
• you require an accounting of who is accessing what.

Otherwise, the individual who created the share represents a single point of failure for determining data access.

See Create a collection and Grant read or write access to a group.

Create a share

Requires: You can read the parent collection — through a read or write grant, as its owner or an admin-group member, as an administrator, or as any signed-in user if the collection is public — and the parent has sharing enabled. See Share administration.

Andrew has access to /riptide-university/reyes-lab/andrews-project, and sharing has been enabled. He goes to create a share so that his classmates can also have access to this namespace.

To create a share:

1. Open Collections and find the parent collection. The share icon appears on its row only when sharing is enabled there.
2. Click the Create share (share) icon.
3. In the Create share of … dialog, fill in Share name, an optional Description, and optionally a Namespace (optional) beneath the parent’s — leave it blank to use the parent’s namespace. (The namespace, if set, has to be equal to, or a subset of, the parent collection’s namespace.)
4. Choose a Visibility. The default is Private.
5. Click CREATE SHARE.

Shares appear in the collections list alongside collections, tagged with a share chip.

Andrew created the share. He owns and manages the share, and when Andrew’s reyes_students grant comes off, the share stops issuing usable tokens.

Give people access to a share

Requires: You are the share’s owner (or server.collection_admin) — see Share administration.

Andrew grants his classmates read, through a group made for the project or through each classmate’s personal user- group.

Access to a share is managed exactly the same as access to a collection. For instructions, see Grant read or write access to a group.

Revoke access

Prerequisites vary by lever — see Collection administration and Share administration.

May is a month of change for the lab.

• May 1st: One of Andrew’s classmates drops the class — Andrew removes that person from the share’s group and touches nothing else.
• May 14th: Andrew is graduating and no longer working with the group - Christina removes Andrew’s membership from reyes_students.
• May 28th: Dr. Reyes decides working with undergraduates is too time-consuming - Christina revokes the reyes_students read grant on the collection entirely.

Three levers, in increasing order of blast radius.

1. Remove the person from the group. Everything else keeps working; only that person loses the access the group carried. See Add and remove group members.

   After Andrew removes his former classmate from the share’s access group, that classmate can no longer access objects via the share.

2. Remove access of the share’s owner to the parent. Not only does the share’s owner lose access, but so does anyone who was accessing objects via the share. See Add and remove group members.

   After Christina removes Andrew from reyes_students, Andrew can no longer access objects in the collection. Furthermore, none of his classmates can use his share anymore.

3. Revoke the grant. The whole group loses that role on that collection. Use the trash icon beside the row under Access groups. See Grant read or write access to a group.

   After Christina removes the reyes_students read grant, no one in the reyes_students group can read objects in the collection, unless they are in a different group that also has read access.

All three take effect the next time a token is issued, not against tokens already in the field. An access token minted before you revoked keeps working until it expires, and the one after it is smaller or empty.

Delete a collection or share

Requires: You are the owner of the collection or share, or server.collection_admin; admin-group members cannot delete — see Collection administration.

Dr. Reyes is considering retirement and asks what should be done about her lab’s collection. Should it be deleted? And if so, how would she go about it?

Deleting a collection removes its grants, its metadata and its list of member objects along with it (but not the objects themselves). Deleting a share is the same operation — a share is a collection — and is done by the share’s owner.

1. Go to the Collections page.
2. Click the Delete collection (trash) icon on the row.

The icon is shown to callers who can edit the collection, which is a slightly wider set than those who can delete it, so an admin-group member may see it and get an error.

In this case, Dr. Reyes decides not to delete the collection.

Transfer ownership of a collection

Requires: You are the current owner or server.collection_admin; admin-group members cannot transfer — see Collection administration.

Dr. Reyes decides to retire and leave the lab to Christina, including ownership of the reyes-lab collection. She must transfer the collection to Christina to enable Christina to manage her own admin users.

Every collection has exactly one owner, and it can be moved but never cleared. There are two routes, depending on whether the new owner already has an account.

If the owner has an account

1. Go to the collection’s Edit collection page.
2. Under the Owner field, select the new owner.
3. Click SAVE CHANGES.

If you hold server.user_admin the picker lists every user on the server; otherwise it offers only the collection’s own people — the current owner, admin-group members, and members of any group already granted access.

Dr. Reyes uses the Edit collection page to transfer ownership of reyes-lab collection to Christina. Ownership is transferred when Dr. Reyes hits SAVE CHANGES.

If the owner does not have an account

Mint an ownership-transfer invite.

A few months later, Christina decides to leave Riptide University and transfer ownership of reyes-lab to a new faculty member.

1. On the Edit collection page, scroll to Transfer via invite link.
2. Click GENERATE TRANSFER LINK.
3. Copy the URL with COPY URL.
4. Send this link to the new owner of the collection.

These links are always single-use. The recipient signs in (self-enrolling through OIDC if this is their first visit), redeems the link, and becomes the owner at that moment; the previous owner loses ownership simultaneously.

Christina sends the new faculty member the invite link. Ownership of reyes-lab collection is transferred when the new faculty member redeems the link.

Doing this from the command line or the API

Reach for these when you are onboarding collections in bulk, or scripting the same handoff for thirty labs instead of one.

The command line. The pelican-server origin collection commands ship in the pelican-server binary. They find your origin by asking the Director (so Federation.DirectorUrl has to be configured), then send you through a browser device-code approval to obtain a token — you do not need shell access on the origin host, but you do need a browser and an account on that origin. In a federation with more than one origin the commands target the first origin the Director returns, so prefer the web interface when several origins are registered. Flags and syntax live in the generated pelican-server origin collection reference.

pelican-server origin collection create \
  --name "Reyes Lab" \
  --namespace /riptide-university/reyes-lab \
  --description "Nearshore current data, Reyes Lab" \
  --visibility private

The command prints the new collection, including its ID, which every later command on that collection needs. Creating a collection from the command line needs the same server.collection_admin (or server.admin) privilege as the web interface.

The API. Every endpoint sits under /api/v1.0/origin_ui/collections, and takes a login cookie or an API token whose creator holds the scope the task calls for. Request and response bodies live in the API browser.

Coverage is not equal across the three, so here is what each one can actually do:

A dash means the web interface is the only option today. pelican-server origin collection update covers the descriptive fields only, which is why the admin group and the sharing switch have no command-line path. The share endpoints (GET and POST /collections/{id}/shares) are also not yet described in the API browser, though the surrounding collection endpoints are.

On the command line, --group-id takes a name: a group name, user-<username> for one person, or @authenticated — never a group’s internal ID, which the command refuses. The API accepts the same names in groupId, or a target by ID through subjectType and subjectId. Either way Pelican resolves the name and stores the target’s immutable ID on the grant, so renaming a group does not break its grants and a reclaimed name inherits nothing. The command line and the API call a collection’s set of grants its ACL (access control list), which is why the subcommand is acl grant; see collection acl.