Skip to main content

​
Overview

Access requests let users ask for permission to a document they can’t currently access. Document owners or admins can then approve or deny these requests. This is the self-service alternative to sharing a document directly.

​
Prerequisites

  • A document ID the requester can see (e.g. via an entry page link)
  • A valid API key

​
Step 1: Inspect Current Access

Before requesting access, check what permissions the caller already has: 
import { Factify } from "@factify/sdk";

const factify = new Factify({ bearerAuth: process.env.FACTIFY_KEY });

async function inspectAccess(documentId: string) {
  const result = await factify.accessRequests.inspectDocumentAccess({
    documentId,
  });

  console.log("Permissions:", result.inspectAccessResponse?.permissionSet);
  return result.inspectAccessResponse;
}

inspectAccess("doc_01h2xcejqtf2nbrexx3vqjhp41");

​
Step 2: Create an Access Request

If the caller lacks the needed permission, create a request: 
async function requestAccess(documentId: string) {
  const result = await factify.accessRequests.createAccessRequest({
    documentId,
    body: {
      permission: "view",
      message: "Need access for quarterly review",
    },
  });

  console.log("Request ID:", result.createAccessRequestResponse?.accessRequest?.id);
  return result.createAccessRequestResponse?.accessRequest;
}

requestAccess("doc_01h2xcejqtf2nbrexx3vqjhp41");

​
Step 3: List Pending Requests (Owner)

The document owner lists pending requests: 
async function listRequests(documentId: string) {
  const result = await factify.accessRequests.listAccessRequests({
    documentId,
  });

  for (const req of result.listAccessRequestsResponse?.items ?? []) {
    console.log(`${req.subjectEmail} requested ${req.permission} access`);
  }
}

listRequests("doc_01h2xcejqtf2nbrexx3vqjhp41");

​
Step 4: Approve or Deny

// Approve
await factify.accessRequests.approveAccessRequest({
  documentId: "doc_01h2xcejqtf2nbrexx3vqjhp41",
  accessRequestId: "acr_01h2xcejqtf2nbrexx3vqjhp42",
  body: {},
});

// Or deny
await factify.accessRequests.denyAccessRequest({
  documentId: "doc_01h2xcejqtf2nbrexx3vqjhp41",
  accessRequestId: "acr_01h2xcejqtf2nbrexx3vqjhp42",
  body: {},
});

​
Response

A created or updated access request: 
{
  "access_request": {
    "id": "acr_01h2xcejqtf2nbrexx3vqjhp42",
    "document_id": "doc_01h2xcejqtf2nbrexx3vqjhp41",
    "subject": {
      "id": "user_01h2xcejqtf2nbrexx3vqjhp43",
      "type": "user_account"
    },
    "subject_email": "alice@example.com",
    "permission": "view",
    "request_status": "pending",
    "message": "Need access for quarterly review",
    "created_at": "2024-06-15T10:30:00Z",
    "updated_at": "2024-06-15T10:30:00Z"
  }
}

​
Permissions

OperationRequired Permission
inspectDocumentAccessAny document visibility
createAccessRequestAny document visibility
listAccessRequestsDocument owner or admin
approveAccessRequestDocument owner or admin
denyAccessRequestDocument owner or admin

​
Next Steps

Share a Document

Share documents via entry pages

Attach a Policy

Apply governance policies