Invitations & Delegated Access

An invitation emails someone who does not yet have a Filedgr account and, when they accept, can grant them access to one of your vaults or streams.

POST /users/{user_id}/invitations              create
GET  /users/{user_id}/invitations              list
GET  /users/{user_id}/invitations/{id}         detail
GET  /users/{user_id}/invitations/statistics   counts per stage

As everywhere on this API, the user_id in the path resolves to the key holder.

Only for people without an account

If the address already belongs to a Filedgr user, creation returns 400. Invitations are not a way to share with existing users — grant them a vault or stream permission directly.

invite_to grants the access

The invite_to field is what turns an invitation into an access grant. Two things about it are easy to get wrong:

warning

invite_to is a JSON string, not a nested object. Serialise it yourself before putting it in the request body. Nothing validates its contents at submission time — a malformed payload is accepted, and fails silently much later when the invitee accepts.

Which permission is granted is decided by which key is present:

Key present	Grants
vault_id	A vault permission
stream_id	A stream permission

Alongside it you must supply every field the corresponding permission request requires: credentials_key, credentials_type (WALLET, EMAIL or API_KEY), action (ADD or REMOVE), network and type (the permission level). A payload missing any of them is accepted at submission time and fails later, when the invitee accepts.

{
  "send_email_to": "someone@example.com",
  "invite_to": "{\"credentials_key\": \"someone@example.com\", \"credentials_type\": \"EMAIL\", \"vault_id\": \"<uuid>\", \"type\": \"VIEWER\", \"action\": \"ADD\", \"network\": \"XRPL\"}"
}

For a stream invitation, swap vault_id for stream_id and use a stream permission type (ADMIN, EDITOR or VIEWER — streams have no OWNER or CUSTOM).

note

Both parties need a wallet credential for the grant to be issued. An invitee without one produces an internal failure rather than a clean error.

Acceptance happens elsewhere

There is no accept endpoint on this API — the invitee accepts through the web application. These routes create and read only.

Acceptance is idempotent: an already-accepted or rejected invitation is returned unchanged and no permission is re-issued. Accepting one invitation also rejects all other pending invitations to the same email address.

warning

When a single user has several pending invitations that each carry an invite_to payload, only one grant is currently issued on acceptance. Send one invitation per person, and grant any further access with explicit permission calls afterwards.

Lifecycle

RECEIVED → SENT → OPENED → CLICKED → ACCEPTED or REJECTED

OPENED and CLICKED come from email engagement tracking, so they depend on the recipient's mail client and may never fire. Status only moves forward — a late tracking event cannot regress a terminal state. GET .../statistics returns counts per stage.