Connect users to third-party OAuth with Gatekeeper

Gatekeeper lets your app ask a user for access to an external account, such as Google Drive, and then use only the access that user approved.

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 TypeScript SDK:

npm install @celestoai/sdk@latest

The TypeScript SDK includes a Gatekeeper client. Python Gatekeeper examples are being updated to the new resource-style SDK.

Quickstart script

Use this complete script to start a connection, list active connections, and list Drive files once OAuth completes.

gatekeeper.ts

import { GatekeeperClient } from "@celestoai/sdk/gatekeeper";

const projectName = process.env.CELESTO_PROJECT_NAME ?? "Default";
const subject = "user:acme:alice"; // Stable identifier for your end user

const client = new GatekeeperClient({
  token: process.env.CELESTO_API_KEY,
});

// Start the connection. The default provider is Google Drive.
const connect = await client.connect({
  subject,
  projectName,
});
console.log("connect:", connect);

if (connect.status === "redirect" && connect.oauthUrl) {
  console.log("OAuth URL:", connect.oauthUrl);
  console.log("Open this URL and complete OAuth before listing files.");
  process.exit(0);
}

const connections = await client.listConnections({ projectName });
console.log("connections:", connections);

const files = await client.listDriveFiles({
  projectName,
  subject,
  pageSize: 10,
  includeFolders: true,
});
console.log("drive_files:", files);

Run it:

export CELESTO_API_KEY="your-api-key"
export CELESTO_PROJECT_NAME="Default"
npx tsx gatekeeper.ts

Expected responses

connect (redirect)

{
  "status": "redirect",
  "oauthUrl": "https://accounts.google.com/o/oauth2/v2/auth?..."
}

connect (connected)

{
  "status": "connected",
  "connectionId": "conn_8e7f4b0b"
}

listConnections

{
  "data": [
    {
      "id": "conn_8e7f4b0b",
      "subject": "user:acme:alice",
      "provider": "google_drive",
      "projectId": "proj_5f2c9f41",
      "accountEmail": "alice@acme.com",
      "status": "ACTIVE"
    }
  ],
  "total": 1
}

listDriveFiles

{
  "files": [
    {
      "id": "1a2b3c4d",
      "name": "Quarterly Report",
      "mimeType": "application/pdf",
      "webViewLink": "https://drive.google.com/file/d/1a2b3c4d/view"
    }
  ],
  "nextPageToken": "Cj4QAA"
}

How the flow works

Create a connection

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 oauthUrl.

Complete OAuth

Send your user to the OAuth URL so they can approve access. The provider calls Celesto back to finalize the connection.

The connection becomes active for that subject.

Use delegated access

List connections, fetch file metadata, update access rules, or revoke access when you are done.

SDK methods

`connect`

connect(payload: {
  subject: string;
  projectName: string;
  provider?: string;
  redirectUri?: string;
}): Promise<GatekeeperConnectResponse>

string

required

Stable identifier for your end user, for example user:acme:alice.

string

required

Your Celesto project name.

string

default:"google_drive"

Provider key. Use google_drive for Google Drive.

string

Optional custom redirect URI after OAuth completion.

`listConnections`

listConnections(payload: {
  projectName: string;
  statusFilter?: string;
}): Promise<GatekeeperListConnectionsResponse>

`listDriveFiles`

listDriveFiles(payload: {
  projectName: string;
  subject: string;
  pageSize?: number;
  pageToken?: string;
  folderId?: string;
  query?: string;
  includeFolders?: boolean;
  orderBy?: string;
}): Promise<GatekeeperDriveListResponse>

`updateAccessRules`

updateAccessRules(payload: {
  subject: string;
  projectName: string;
  accessRules: {
    allowedFolders?: string[];
    allowedFiles?: string[];
  };
}): Promise<GatekeeperAccessRules>

Use access rules to limit which folders or files the connection can read.

`revokeConnection`

revokeConnection(payload: {
  subject: string;
  projectName: string;
  provider?: string;
}): Promise<GatekeeperRevokeResponse>

Use this when the user disconnects their account or your app no longer needs access.

Start Here

Features

Guides

Agents and Integrations

Connect users to third-party OAuth with Gatekeeper

Prerequisites

Quickstart script

Expected responses

How the flow works

SDK methods

`connect`

`listConnections`

`listDriveFiles`

`updateAccessRules`

`revokeConnection`

​Prerequisites

​Quickstart script

​Expected responses

​How the flow works

​SDK methods

​connect

​listConnections

​listDriveFiles

​updateAccessRules

​revokeConnection

Prerequisites

Quickstart script

Expected responses

How the flow works

SDK methods

`connect`

`listConnections`

`listDriveFiles`

`updateAccessRules`

`revokeConnection`