API reference

Access requests API

When a link turns somebody away — not on its allow-list, outside its domains, or outside its viewer group — they can ask for access. These endpoints list those requests and answer them.

Create an API key Quick start

Base URL https://xdocs.io/api/v1, with Authorization: Bearer xdk_… on every request. Pagination, rate limits, scopes and error codes are the same for every endpoint and are described once, in how the API behaves.

Access requests

People a link turned away — not on its allow-list, outside its domains, on its blocked list or outside its viewer group — or who opened a document's editor URL or a room's page without being able to reach it, and asked to be let in. Nothing changes until you approve.

GET/api/v1/access-requestslinks:read

Access requests, newest first. Pending only unless status says otherwise; at most two hundred.

Query parameters

statusstring: pending (default), approved, denied or all.
documentIdstring
dataRoomIdstring
shareLinkIdstring
emailstring

Returns

{ data: AccessRequest[] } — id, documentId (null for a room request), dataRoomId, shareLinkId (null for a request made from the document's or room's own URL), linkName, about (the document or room title), email, verified (the address was proven by sign-in or the link's email code, not just typed), message, requestedRole, status, grantedRole, createdAt, decidedAt, decidedBy

400 `status` is not one of the four values.

GET/api/v1/access-requests/:idlinks:read

One access request, whatever its status.

Returns

{ data: AccessRequest }

POST/api/v1/access-requests/:id/decidelinks:write

Approve or deny. Approving a link request adds the address to that link's allow-list (or its viewer group) and removes an exact blocked-list entry; approving a document request makes them a collaborator at role. Approving a room request from a member of the workspace limited to other rooms adds the room to their rooms; for anybody else it follows grant. The requester is emailed on approval (a room-limited invitation sends the team invitation instead); a denial mails nobody.

Body (JSON)

decisionstringrequired: approve or deny.
rolestring: For a document request: viewer, commenter or editor. Defaults to what they asked for. Ignored for link and room requests.
grantstring: For a room request from outside the workspace: group adds them to one of the room's viewer groups (the least access — they read through that group's link, only what it may see); invite invites them to the team as a member limited to this room (a seat; not possible in a personal workspace). Defaults to group when the room has exactly one viewer group with a live link. Ignored for other requests.
groupIdstring: With grant: "group": which of the room's viewer groups. Implies grant: "group".

Returns

{ data: AccessRequest, delivered: boolean, note: string } — delivered says whether the approval email went

409 Already decided, or the grant cannot be made: the link, document or room was deleted, a blocked domain on the link covers the address, the workspace is personal (no `invite`), or the plan has no seat left.
400 A room request from outside the workspace with no `grant` to follow, or `groupId` is not one of the room's viewer groups.

← The whole API reference Next: Viewer questions API →