​
Usage

The Permissions API uses the same base URL and authorization details as the Sync API.

​
About Permission Syncs

Permission Syncs use available APIs to query all ways that users can access or inherit access to a file.

For example, for the Google Drive integration, Paragon syncs permissions for:

  • Direct access assigned to files
  • Inherited access from parent folders
  • Google Group member access (direct or inherited)
  • Google Workspace organization-wide access
    • If not designated as “searchable by organization”: access granted from an opened link

Because evaluating permissions can be difficult and error-prone in practice, Permission Syncs store permission data in a fine-grained authorization server that dramatically simplifies the query to check for access.

Instead of searching across role relationships and executing specific rules for each integration, you can query the Permissions API in a standard format:

Query to check if a user has access to File ID
{
    "user": "user:[email protected]",
    "role": "can_read",
    "object": "[File UUID]"
}

This query format works across any File Storage sync that supports Permissions.

Permission Syncs are currently supported on a select number of File Storage integrations and run automatically when files are processed.

​
Implementing Permissions API

To implement Permissions API in a production context, your application will need to query the Permissions API to check for access when documents are being requested.

Below is a diagram illustrating how Sync API and Permissions API can be used together in a RAG-based chat application (“Your App”) where an organization admin connects their Google Workspace to your app to ingest workspace files on behalf of everyone in that organization.

Permissions API can be used to filter documents that match the user’s query from your vector/search database to only the files that the user has access to in Google Workspace.

Depending on the architecture of your app or database, you may use one of the following patterns to integrate Permissions API:

  • Search, then filter results: Use your search database (e.g. Pinecone) for relevant documents, and use Batch Check Access to filter the result set to the documents that the user has access to.
    • Best for RAG apps, where the search result set is bounded to a threshold of semantically relevant documents.
    • This is the pattern illustrated in the above diagram.
  • List all searchable objects, then search: Use List Objects to enumerate all searchable documents, and provide this list as a metadata filter on the query to your search database.
    • Ideal for apps where the number of possible documents associated with a given user is low (e.g. < 1000)