Skip to main content
Delegated Access lets you connect your end users (subjects) to third-party providers such as Google Drive while keeping access scoped to your project.

​
Prerequisites

You can find your API key and project name in the Celesto Dashboard.
Set the following environment variables:
  • CELESTO_API_KEY: Your Celesto API key
  • CELESTO_PROJECT_NAME: Your project name
Install the SDK: 
pip install celesto

​
Quickstart script

Use this complete script to start a connection, list active connections, and list Drive files once OAuth completes. 
import os
from celesto.sdk import CelestoSDK


project_name = "Default"
subject = "user:acme:alice"  # Unique identifier for your end user

client = CelestoSDK()

# ====================================================================

# Initiate connection (returns oauth_url if authorization is required)
response = client.gatekeeper.connect(
    subject=subject,
    provider="google_drive",
    project_name=project_name,
)
print("connect:", response)

if response.get("oauth_url"):
    print("OAuth URL:", response["oauth_url"])
    print("Complete OAuth flow before continuing...")
    raise SystemExit

print("Connected! Status:", response.get("status"))

# ====================================================================

# List current connections
connections = client.gatekeeper.list_connections(project_name=project_name)
print("connections:", connections)

# ====================================================================

# List Drive files for the subject
files = client.gatekeeper.list_drive_files(
    project_name=project_name,
    subject=subject,
    page_size=10,
    include_folders=True,
)
print("drive_files:", files)

# ====================================================================

# Update access rules (restrict to specific folders)
# rules = client.gatekeeper.update_access_rules(
#     subject=subject,
#     project_name=project_name,
#     allowed_folders=["folder_id_1", "folder_id_2"],
# )
# print("access_rules:", rules)

# ====================================================================

# Revoke connection when done
# client.gatekeeper.revoke_connection(
#     subject=subject,
#     project_name=project_name,
# )

​
Expected responses

connect (redirect)
{
  "status": "redirect",
  "oauth_url": "https://accounts.google.com/o/oauth2/v2/auth?..."
}
connect (connected)
{
  "status": "connected",
  "connection_id": "conn_8e7f4b0b"
}
list_connections
{
  "data": [
    {
      "id": "conn_8e7f4b0b",
      "subject": "user:acme:alice",
      "provider": "google_drive",
      "project_id": "proj_5f2c9f41",
      "account_email": "[email protected]",
      "scopes": ["https://www.googleapis.com/auth/drive.readonly"],
      "status": "ACTIVE",
      "created_at": "2025-12-10T19:22:11Z",
      "updated_at": "2025-12-10T19:25:45Z",
      "last_used_at": "2025-12-11T10:01:12Z"
    }
  ],
  "total": 1
}
list_drive_files
{
  "files": [
    {
      "id": "1a2b3c4d",
      "name": "Quarterly Report",
      "mime_type": "application/pdf",
      "size": 482133,
      "modified_time": "2025-12-01T08:10:22Z",
      "web_view_link": "https://drive.google.com/file/d/1a2b3c4d/view"
    }
  ],
  "next_page_token": "Cj4QAA"
}
error
{
  "detail": "OAuth not configured for provider: google_drive"
}

​
How the flow works

1

Create a connection

You call connect with a subject and project name. If the subject has not authorized yet, you receive an OAuth URL.
You get status: redirect and an oauth_url.
2

Complete OAuth

You send your user to the OAuth URL and complete consent. The provider calls Celesto back to finalize the connection.
The connection becomes ACTIVE for that subject.
3

Use delegated access

You list connections, fetch file metadata, and optionally revoke access when you are done.

​
SDK methods

Python uses snake_case parameters (e.g., project_name, page_size). JavaScript uses camelCase (e.g., projectName, pageSize).

​
connect

Signature: 
connect(
    subject: str, 
    project_name: str, 
    provider: str = "google_drive", 
    redirect_uri: str | None = None
) -> dict
Parameters
​
subject
string
required
Stable identifier for your end user (for example, user:acme:alice)
​
project_name
string
required
Your Celesto project name
​
provider
string
default:"google_drive"
Provider key. Use google_drive for Google Drive
​
redirect_uri
string
Optional custom redirect URI after OAuth completion

​
list_connections

Signature: 
list_connections(
    project_name: str, 
    status_filter: str | None = None
) -> dict
Parameters
​
project_name
string
required
Your Celesto project name
​
status_filter
string
Filter by status: ACTIVE, PENDING, or REVOKED

​
get_connection

Signature: 
get_connection(connection_id: str) -> dict
Parameters
​
connection_id
string
required
Delegated connection ID

​
list_drive_files

Signature: 
list_drive_files(
    project_name: str, 
    subject: str, 
    page_size: int = 20, 
    page_token: str | None = None, 
    folder_id: str | None = None, 
    query: str | None = None, 
    include_folders: bool = True, 
    order_by: str | None = None
) -> dict
Parameters
​
project_name
string
required
Your Celesto project name
​
subject
string
required
Subject identifier tied to the delegated connection
​
page_size
integer
default:"20"
Number of files to return (1-1000)
​
page_token
string
Token from a previous response for pagination
​
folder_id
string
Google Drive folder ID. Defaults to root unless query is provided
​
query
string
Google Drive search query (q parameter)
​
include_folders
boolean
default:"true"
Include folders in the results
​
order_by
string
Google Drive orderBy parameter
If access rules are active, a page may contain fewer than page_size results after filtering. Use next_page_token to continue.

​
update_access_rules

Signature: 
update_access_rules(
    subject: str,
    project_name: str,
    allowed_folders: list[str] | None = None,
    allowed_files: list[str] | None = None,
    provider: str | None = None
) -> dict
Parameters
​
subject
string
required
Subject identifier (e.g., user:acme:alice)
​
project_name
string
required
Your Celesto project name
​
allowed_folders
string[]
List of Google Drive folder IDs with recursive access
​
allowed_files
string[]
List of individual Google Drive file IDs
​
provider
string
Optional provider filter (e.g., google_drive)
Setting both lists to empty blocks all access. Use clear_access_rules to remove restrictions.

​
clear_access_rules

Signature: 
clear_access_rules(connection_id: str) -> dict
Parameters
​
connection_id
string
required
Delegated connection ID

​
revoke_connection

Signature: 
revoke_connection(
    subject: str,
    project_name: str,
    provider: str | None = None
) -> dict
Parameters
​
subject
string
required
Subject identifier (e.g., user:acme:alice)
​
project_name
string
required
Your Celesto project name
​
provider
string
Optional provider filter (e.g., google_drive)

​
Troubleshooting

  • Ensure Google OAuth is configured for delegated access in your Celesto settings.
  • Verify you are using provider="google_drive" and the correct project name.
  • Make sure the user completed the OAuth flow in the browser.
  • Check that the callback URL is reachable from the OAuth provider.

​
Next steps

  • Review the Google OAuth setup guide in superauth/google-oauth-setup.
  • Use get_connection to inspect scopes and last usage when you debug access.