API

Sharing

Share a resource with people, groups, circles or a link, change and pause what each sees, accept offers, and see what is shared with you.

A resource is named <app>:<type>:<id> (a car is vehicles:vehicle:veh_…), URL-encoded in paths. You share only what you hold, and never more than you hold. Someone outside your circles or organization accepts a share before it gives them anything. Reading needs sharing:read; sharing, changing, pausing and ending need sharing:write. A person's live location is shared through Find My instead.

Every route below, with its parameters, request and response, errors and samples, is in the API reference.

Route	What it does
`GET /v1/sharing/resources/:rn`	What you hold on a resource and where it comes from (`you`). If you may share it, also who has access (each grant with its `rev`, preset, limits and whether the owner organization's policy blocks it), its links, invitations to addresses with no account, and the owner organization's policy. No access, or no such resource, is 404.
`POST /v1/sharing/resources/:rn/grants`	Shares a resource with a person (by `user` id or email address), group, circle, organization or key: a `preset` or a list of `capabilities`, and optionally `notBefore`, `expiresAt`, a weekly `schedule`, `params`, `assistants`, `approval` and a `message`. You can give no more than you hold. 201 with `{ kind: "grant" }` (`pending` when the person must accept) or, for an address with no account, `{ kind: "invitation" }`, which becomes a pending grant when they sign up. 403 `external_sharing_off` when the owner organization's policy refuses it, 403 `capability_not_held_to_grant` for more than you hold, 429 past the daily limit.
`PATCH /v1/sharing/resources/:rn/grants/:principal`	Changes a grant made directly: send the `rev` you read and the fields to change (`null` clears `notBefore`, `expiresAt`, `schedule`, `params` and `approval`; naming `preset` replaces the capabilities and settings). The result is held to the same rules as a new grant. 409 `stale` (with the grant as it is now) when someone changed it first. `?source=` picks one when a principal holds several.
`DELETE /v1/sharing/resources/:rn/grants/:principal`	Ends a grant, or withdraws an invitation, for those who may share the resource, and for the grantee leaving. `?source=` picks one when a principal holds several; `?rev=` makes it conditional (409 `stale`). The person is told unless `?notify=false`. 204.
`PUT /v1/sharing/resources/:rn/grants/:principal/pause`	Pauses a grant made directly: `{ until }` (epoch seconds in the future, or `forever` until it is resumed), with an optional `rev`. Paused, it gives only what stays on outside a schedule (a car's name and status, not where it is or whether it moves; a person's location gives nothing), and the grantee gets no notice; their requests answer 403 `paused`. For whoever may change the grant. Audited as `share.pause`.
`DELETE /v1/sharing/resources/:rn/grants/:principal/pause`	Resumes a paused grant at once. Audited as `share.resume`.
`DELETE /v1/sharing/resources/:rn/invitations/:invitationId`	Withdraws an invitation to an address with no account, by its id (the address never goes in a URL), for its maker, the owner and role holders. 204.
`POST /v1/sharing/resources/:rn/links`	Makes a link to a resource: an `audience` (`anyone`, `signed_in`, or `org` for the owner organization's members), a `preset` or `capabilities` the type lets a link carry, an `expiresAt` within the longest the type allows, and an optional `password`. 201 with the link and its `url`, which is shown once and cannot be read again.
`DELETE /v1/sharing/links/:linkId`	Ends a link and the access it gave. The person who made it, or anyone who may share the resource. 204; a link that isn't there (or isn't yours to see) is 404.
`GET /v1/sharing/resources/:rn/check`	Whether a person (`principal=user:usr_…`) holds a `capability` on the resource and where it comes from, for those who may share it and for holders of `tenant:read` in the owner organization. Nothing is audited: it is a question, not a use.
`GET /v1/me/shared`	What is shared with you, your groups and your circles, newest first within a page (`app`, `type`, `cursor`, `limit`). Pages follow your principals one after another, so one can be short: carry on while `cursor` is set. The first page also turns invitations to your address into pending offers.
`GET /v1/me/shared/pending`	Offers waiting for you to accept (people outside your circles and organization share by offer), with what the owner can see of your use to read first (`disclosure`). They give nothing until accepted and lapse after 30 days.
`POST /v1/me/shared/:grantKey/accept`	Accepts an offer: it becomes access, ending when the sharer said. 410 `offer_lapsed` once its 30 days ran out. Recorded in your log and the owner's.
`POST /v1/me/shared/:grantKey/decline`	Declines an offer; the sharer is told. 204.
`GET /v1/me/sharing/out`	What you share from your Personal space: the grants (newest first, paged by `cursor`) and, on the first page, your links.
`GET /v1/me/shared`	What is shared with you, your groups and your circles, newest first within a page (`app`, `type`, `cursor`, `limit`). Pages follow your principals one after another, so one can be short: carry on while `cursor` is set. The first page also turns invitations to your address into pending offers.
`GET /v1/me/shared/pending`	Offers waiting for you to accept (people outside your circles and organization share by offer), with what the owner can see of your use to read first (`disclosure`). They give nothing until accepted and lapse after 30 days.
`POST /v1/me/shared/:grantKey/accept`	Accepts an offer: it becomes access, ending when the sharer said. 410 `offer_lapsed` once its 30 days ran out. Recorded in your log and the owner's.
`POST /v1/me/shared/:grantKey/decline`	Declines an offer; the sharer is told. 204.
`GET /v1/me/sharing/out`	What you share from your Personal space: the grants (newest first, paged by `cursor`) and, on the first page, your links.