Sharing groups API
Ce contenu n’est pas encore disponible dans votre langue.
Groups are created and filled by admins, then datasets, maps and stories are shared with them. The behavior behind these routes is described in Sharing with groups. Request and response schemas are in the API reference.
Replace https://geolens.example.com, $TOKEN and the ids below with your
own values. Send the token as a bearer token or API key, as described in
API authentication.
Admin routes
Section titled “Admin routes”These need the manage_users permission. Names are unique, and a duplicate
answers 409.
| Method and path | Purpose |
|---|---|
GET /admin/groups/ | List groups by name, with member_count. Takes skip and limit. |
POST /admin/groups/ | Create a group from {"name": "Planning"}. Answers 201. |
GET /admin/groups/{group_id} | Read one group. |
PATCH /admin/groups/{group_id} | Rename it with {"name": "..."}. |
DELETE /admin/groups/{group_id} | Delete it and its memberships. Answers 204. |
GET /admin/groups/{group_id}/members/ | List members by username. |
POST /admin/groups/{group_id}/members/ | Add users with {"user_ids": [...]}, up to 500. Users already in the group are skipped. An unknown id answers 404 and adds nobody. |
DELETE /admin/groups/{group_id}/members/{user_id} | Remove one member. Answers 204. |
curl -X POST https://geolens.example.com/api/admin/groups/ \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "Planning"}'Deleting a group removes its grants at once. A restricted map or story shared only with it becomes private. Adding a member answers 422 when a virtual raster dataset shared with the group would then reach someone who can’t read one of its sources.
List the groups you can share with
Section titled “List the groups you can share with”curl "https://geolens.example.com/api/groups/mine/" \ -H "Authorization: Bearer $TOKEN"Returns {"groups": [{"id": "...", "name": "..."}], "total": 1}. The groups
are the ones the caller belongs to, or every group for an admin. skip and
limit (default 50, at most 200) page the list.
Share a dataset
Section titled “Share a dataset”curl -X PUT "https://geolens.example.com/api/datasets/$DATASET_ID/groups/" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"group_ids": ["'"$GROUP_ID"'"]}'group_ids is the full list, up to 100, and replaces what the dataset had. An
empty list removes every group. The caller needs the edit_metadata permission
and must own the dataset or be an admin.
- A private dataset with a group becomes
restricted. A restricted dataset left with no group becomesprivate. Internal and public datasets keep their visibility. - An owner who adds a group they don’t belong to gets 403. An unknown group answers 404.
- A change that would strand a layer in one of the owner’s shared maps, or
expose a source through a virtual raster dataset, answers 422. So does
DELETEon a dataset one of the owner’s shared maps shows, or whose map holds an active embed token. The body carriescodedataset_in_shared_maps,actionandshared_mapsbesidedetail, so a client can name the blocking maps. Bulk delete refuses that item with the same code and deletes the others.
Dataset detail returns groups to the owner and admins only.
Share a map
Section titled “Share a map”curl -X PUT "https://geolens.example.com/api/maps/$MAP_ID/groups/" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"group_ids": ["'"$GROUP_ID"'"]}'The body and the visibility rules match the dataset route, with the map’s own
owner-or-admin check. The response carries visibility, groups,
shared_dataset_ids and hidden_layers. Becoming restricted revokes the
map’s share link and embed tokens.
Confirm sharing layers the groups can’t read
Section titled “Confirm sharing layers the groups can’t read”When a member of a new group can’t read a layer’s dataset, nothing is written and the route answers 409:
{ "detail": { "code": "layers_hidden_from_groups", "message": "...", "layers": [ { "layer_id": "...", "layer_title": "Parcels", "dataset_id": "...", "dataset_title": "Parcels 2026", "group_ids": ["..."], "can_share": true } ] }}Repeat the request with confirm:
"share_datasets"also shares each dataset withcan_share: truewith the groups that lack it. A refusal on any of those shares rolls back the whole request, the map’s groups included."map_only"shares the map alone. The response’shidden_layerslists the layers still out of reach.
Branch on detail.code. A 409 without it means another change holds the map’s
lock, and the request can be retried.
GET /maps/{id}/visibility-check/ also returns hidden_from_groups: on a
restricted map, the layers some of its groups can’t read, among those the
caller can read.
Share a story
Section titled “Share a story”curl -X PUT "https://geolens.example.com/api/stories/$STORY_ID/groups/" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"group_ids": ["'"$GROUP_ID"'"]}'group_ids is the full list, up to 100, and replaces what the story had. An
empty list removes every group. The caller needs the edit_metadata permission
and must own the story or be an admin. An owner who adds a group they don’t
belong to gets 403, and an unknown group answers 404.
A private story with a group becomes restricted. A restricted story left with
no group becomes private. Internal and public stories keep their visibility,
and a story with groups stays restricted when you set it to private. Once
the story is published, members of its groups can read it and its images. The
response carries visibility, groups and shared_map_ids. A story’s
groups also appear on its draft, for the owner and admins only.
Story responses name restricted without the map visibility header below.
Confirm sharing maps the groups can’t read
Section titled “Confirm sharing maps the groups can’t read”Sharing a published story, and POST /stories/{id}/publish for a story with
groups, are refused while a member of its groups can’t open one of the maps its
chapters use. The route answers 409 and writes nothing:
{ "detail": { "code": "maps_narrower_than_story", "message": "...", "maps": [{ "id": "...", "name": "Parcels", "can_share": true }], "unreadable_maps": 0 }}detail.maps lists the maps the caller can read. detail.unreadable_maps
counts the rest. Repeat the request with "confirm": "share_maps" to share each
map with can_share: true with the groups that lack it first. A private map
shared this way becomes restricted, which revokes its share link and embed
tokens. The request is still refused while another map blocks it.
Read restricted maps
Section titled “Read restricted maps”A map can now be restricted. Older generated clients reject a visibility
value they don’t know, so a map response names restricted only to clients
that send this request header:
X-GeoLens-Map-Visibility: restrictedEvery map-returning endpoint answers with Vary: X-GeoLens-Map-Visibility.
Without the header a restricted map reads as private, and the
visibility=private list filter also finds restricted maps. Writing private
to a map that has groups keeps it restricted, so a client that can’t see the
groups doesn’t remove them by accident. Remove them with
PUT /maps/{id}/groups/ and an empty list. PUT /maps/{id} with
visibility: restricted and no group answers 422.
The web app, the CLI, the MCP server and both SDKs send the header. A later
release will name restricted to every client, header or not, so a client that
sends it now sees no change then.
404 instead of 403 on maps
Section titled “404 instead of 403 on maps”Map write and management routes answer 404, not 403, for a map the caller can’t read, so they no longer reveal that it exists. A caller who can read the map but doesn’t own it still gets 403.
Next steps
Section titled “Next steps”- Sharing with groups: the same feature from the app.
- User management: create users and the groups they join.
- Authentication: keys and tokens for the calls above.