Integration & Sync

Cloud integration connections and sync operations for the cloud library drivers (Google Drive, OneDrive, Box, GitHub).

A cloud library owns an embedded integration (its OAuth client config) and, once authorized, a connection (the OAuth tokens). The integration is provisioned when the cloud library is created; the connection is established through the OAuth flow.

GET /api/libraries/{id}/integration

Get the embedded integration for a library.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Library id or natural id

Response:

The embedded integration with its OAuth client config. The stored client secret comes back as an encrypted blob, never in clear text. A local library has no integration, so this returns 404.

Get the embedded integrationGET /api/libraries/admin:engineering-drive/integration

For a cloud library, the embedded integration that carries its OAuth client config. Returns 404 for a local library (no integration).

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/integration"
    },
    "inf:integration-share": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/integration/shares/{principalId}",
      "templated": true
    },
    "inf:icon": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/integration/icon"
    },
    "inf:connect": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/integration/connect"
    },
    "inf:connection": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/integration/connection"
    },
    "inf:request": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/integration/request"
    },
    "inf:favorite": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/integration/favorite"
    },
    "inf:integration-owner": {
      "href": "https://informer.example.com/api/integrations/admin%3Agoogle-drive/owner"
    },
    "inf:integration-shares": {
      "href": "https://informer.example.com/api/integrations/admin%3Agoogle-drive/shares"
    }
  },
  "naturalId": "admin:google-drive",
  "driver": {
    "id": "api",
    "editorComponent": "apiIntegrationEditor",
    "extraAuthUriParams": {},
    "supportsUpload": false
  },
  "iconUrl": "/images/icons/integrations/googledrive.svg",
  "permissions": {
    "write": true,
    "edit": true,
    "delete": true,
    "share": true,
    "assignTags": true,
    "changeOwner": true
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "name": "Google Drive",
  "slug": "google-drive",
  "description": "Access your Google Drive files",
  "category": "Google Drive",
  "type": "api",
  "mode": "shared",
  "authType": "oauth2",
  "basicTokenAuth": false,
  "data": null,
  "embedded": true,
  "clientId": "123456789-abcdefg.apps.googleusercontent.com",
  "clientSecret": "encrypted:iv:0000000000000000",
  "apiKey": null,
  "apiKeyLocation": null,
  "apiKeyName": null,
  "headers": {},
  "scope": "https://www.googleapis.com/auth/drive.readonly",
  "apiBaseUri": "https://www.googleapis.com",
  "authUri": "https://accounts.google.com/o/oauth2/v2/auth",
  "tokenUri": "https://oauth2.googleapis.com/token",
  "revocationUri": null,
  "imageUrl": "/images/icons/integrations/googledrive.svg",
  "libraryId": "00000000-0000-4000-8000-000000000002",
  "mailTenantId": null,
  "ownerId": "admin",
  "shared": false,
  "folderId": null,
  "source": null,
  "sourceId": null,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "tenant": "acme",
  "icon": null
}

Captured from the API examples test suite; ids and timestamps are normalized.

---

PUT /api/libraries/{id}/integration

Create or update the embedded integration's client credentials.

Authentication: Required

Permissions: Requires library:editConnection

Path Parameters:

Parameter	Type	Description
id	string	Library id or natural id

Request Body:

Field	Type	Required	Description
clientId	string	No	OAuth client id
clientSecret	string	No	OAuth client secret. Omit to leave the stored secret unchanged
readOnly	boolean	No	Selects the OAuth scope (read-only vs read-write)

Example:

{ "clientId": "987654321-zyxwvu.apps.googleusercontent.com", "readOnly": true }

Response:

Responds 200 with the reloaded library.

Update the embedded integrationPUT /api/libraries/admin:engineering-drive/integration

Body is { clientId, clientSecret?, readOnly? } (not an integrationId). Omit clientSecret to leave the stored one unchanged; readOnly selects the OAuth scope. Responds with the reloaded library.

Request body

{
  "clientId": "987654321-zyxwvu.apps.googleusercontent.com",
  "readOnly": true
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/integration"
    },
    "inf:library-share": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/shares/{principalId}",
      "templated": true
    },
    "inf:assistants": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/assistants"
    },
    "inf:sync": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/_sync"
    },
    "inf:files": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/files"
    },
    "inf:account": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/account"
    },
    "inf:library-owner": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/owner"
    },
    "inf:library-shares": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/shares"
    },
    "inf:comments": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/integration/comments"
    },
    "inf:library-assistant-access": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/integration/assistant-access"
    },
    "inf:favorite": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/favorite"
    },
    "inf:library-integration": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/integration/integration"
    }
  },
  "naturalId": "admin:engineering-drive",
  "isLocal": false,
  "permissions": {
    "assignTags": true,
    "changeOwner": true,
    "configure": false,
    "connect": true,
    "edit": true,
    "delete": true,
    "write": true,
    "sync": true,
    "rename": true,
    "share": true,
    "editConnection": true
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "type": "googledrive",
  "name": "Engineering Drive",
  "slug": "engineering-drive",
  "description": null,
  "ownerId": "admin",
  "data": {
    "folderId": "1A2B3C4D5E6F7G8H9I0J"
  },
  "folderId": null,
  "shared": false,
  "assistantAccess": false,
  "embedded": false,
  "syncedAt": null,
  "syncInterval": 1440,
  "snapshotOfId": null,
  "chatId": null,
  "source": null,
  "sourceId": null,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "tenant": "acme",
  "_embedded": {
    "inf:library-driver": {
      "_links": {
        "self": {
          "href": "https://informer.example.com/api/library-drivers/googledrive"
        }
      },
      "id": "googledrive",
      "name": "Google Drive™",
      "imageUrl": "/images/icons/integrations/googledrive.svg",
      "configComponent": "googledriveConfig",
      "editorComponent": {
        "clientIdSecretForm": {
          "type": "googledrive"
        }
      },
      "defaultSyncInterval": 1440,
      "isLocal": false
    },
    "inf:integration": {
      "_links": {
        "self": {
          "href": "https://informer.example.com/api/integrations/google-drive"
        },
        "inf:integration-share": {
          "href": "https://informer.example.com/api/integrations/google-drive/shares/{principalId}",
          "templated": true
        },
        "inf:icon": {
          "href": "https://informer.example.com/api/integrations/google-drive/icon"
        },
        "inf:connect": {
          "href": "https://informer.example.com/api/integrations/google-drive/connect"
        },
        "inf:connection": {
          "href": "https://informer.example.com/api/integrations/google-drive/connection"
        },
        "inf:request": {
          "href": "https://informer.example.com/api/integrations/google-drive/request"
        },
        "inf:favorite": {
          "href": "https://informer.example.com/api/integrations/google-drive/favorite"
        },
        "inf:integration-owner": {
          "href": "https://informer.example.com/api/integrations/admin%3Agoogle-drive/owner"
        },
        "inf:integration-shares": {
          "href": "https://informer.example.com/api/integrations/admin%3Agoogle-drive/shares"
        }
      },
      "naturalId": "admin:google-drive",
      "driver": {
        "id": "api",
        "editorComponent": "apiIntegrationEditor",
        "extraAuthUriParams": {},
        "supportsUpload": false
      },
      "iconUrl": "/images/icons/integrations/googledrive.svg",
      "permissions": {
        "write": true,
        "edit": true,
        "delete": true,
        "share": true,
        "assignTags": true,
        "changeOwner": true
      },
      "id": "00000000-0000-4000-8000-000000000002",
      "name": "Google Drive",
      "slug": "google-drive",
      "description": "Access your Google Drive files",
      "category": "Google Drive",
      "type": "api",
      "mode": "shared",
      "authType": "oauth2",
      "basicTokenAuth": false,
      "data": null,
      "embedded": true,
      "clientId": "987654321-zyxwvu.apps.googleusercontent.com",
      "clientSecret": "encrypted:iv:0000000000000000",
      "apiKey": null,
      "apiKeyLocation": null,
      "apiKeyName": null,
      "headers": {},
      "scope": "https://www.googleapis.com/auth/drive.readonly",
      "apiBaseUri": "https://www.googleapis.com",
      "authUri": "https://accounts.google.com/o/oauth2/v2/auth",
      "tokenUri": "https://oauth2.googleapis.com/token",
      "revocationUri": null,
      "imageUrl": "/images/icons/integrations/googledrive.svg",
      "libraryId": "00000000-0000-4000-8000-000000000001",
      "mailTenantId": null,
      "ownerId": "admin",
      "shared": false,
      "folderId": null,
      "source": null,
      "sourceId": null,
      "createdAt": "2026-01-15T16:20:00.000Z",
      "updatedAt": "2026-01-15T16:20:00.000Z",
      "tenant": "acme",
      "connections": [],
      "icon": null
    }
  }
}

Captured from the API examples test suite; ids and timestamps are normalized.

Not an integrationId

This endpoint configures the library's own embedded integration in place. It does not take an integrationId to link an external integration.

---

GET /api/libraries/{id}/connection

Get the OAuth connection status for a library's integration.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Library id or natural id

Response:

Token and refresh-token expiry plus the last authorization time. The tokens themselves are never returned. Responds 404 when the library has not been connected.

Get the OAuth connectionGET /api/libraries/admin:engineering-drive/connection

Connection status for the library’s integration (token/refresh expiry and last authorization). Tokens themselves are never returned. Responds 404 when the library has not been connected.

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-drive/connection"
    }
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "tokenExpiresAt": "2026-01-15T16:20:00.000Z",
  "refreshTokenExpiresAt": "2026-01-15T16:20:00.000Z",
  "lastAuthorizedAt": "2026-01-15T16:20:00.000Z",
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "tenant": "acme",
  "ownerId": "admin",
  "integrationId": "00000000-0000-4000-8000-000000000002",
  "_embedded": {
    "inf:integration": {
      "_links": {
        "self": {
          "href": "https://informer.example.com/api/integrations/00000000-0000-4000-8000-000000000002"
        },
        "inf:integration-share": {
          "href": "https://informer.example.com/api/integrations/00000000-0000-4000-8000-000000000002/shares/{principalId}",
          "templated": true
        },
        "inf:icon": {
          "href": "https://informer.example.com/api/integrations/00000000-0000-4000-8000-000000000002/icon"
        },
        "inf:connect": {
          "href": "https://informer.example.com/api/integrations/00000000-0000-4000-8000-000000000002/connect"
        },
        "inf:connection": {
          "href": "https://informer.example.com/api/integrations/00000000-0000-4000-8000-000000000002/connection"
        },
        "inf:request": {
          "href": "https://informer.example.com/api/integrations/00000000-0000-4000-8000-000000000002/request"
        },
        "inf:favorite": {
          "href": "https://informer.example.com/api/integrations/00000000-0000-4000-8000-000000000002/favorite"
        },
        "inf:integration-owner": {
          "href": "https://informer.example.com/api/integrations/admin%3Agoogle-drive/owner"
        },
        "inf:integration-shares": {
          "href": "https://informer.example.com/api/integrations/admin%3Agoogle-drive/shares"
        }
      },
      "naturalId": "admin:google-drive",
      "driver": {
        "id": "api",
        "editorComponent": "apiIntegrationEditor",
        "extraAuthUriParams": {},
        "supportsUpload": false
      },
      "iconUrl": "/images/icons/integrations/googledrive.svg",
      "permissions": {
        "write": true,
        "edit": true,
        "delete": true,
        "share": true,
        "assignTags": true,
        "changeOwner": true
      },
      "id": "00000000-0000-4000-8000-000000000002",
      "name": "Google Drive",
      "slug": "google-drive",
      "description": "Access your Google Drive files",
      "category": "Google Drive",
      "type": "api",
      "mode": "shared",
      "authType": "oauth2",
      "basicTokenAuth": false,
      "data": null,
      "embedded": true,
      "clientId": "987654321-zyxwvu.apps.googleusercontent.com",
      "clientSecret": "encrypted:iv:0000000000000000",
      "apiKey": null,
      "apiKeyLocation": null,
      "apiKeyName": null,
      "headers": {},
      "scope": "https://www.googleapis.com/auth/drive.readonly",
      "apiBaseUri": "https://www.googleapis.com",
      "authUri": "https://accounts.google.com/o/oauth2/v2/auth",
      "tokenUri": "https://oauth2.googleapis.com/token",
      "revocationUri": null,
      "imageUrl": "/images/icons/integrations/googledrive.svg",
      "libraryId": "00000000-0000-4000-8000-000000000003",
      "mailTenantId": null,
      "ownerId": "admin",
      "shared": false,
      "folderId": null,
      "source": null,
      "sourceId": null,
      "createdAt": "2026-01-15T16:20:00.000Z",
      "updatedAt": "2026-01-15T16:20:00.000Z",
      "tenant": "acme",
      "icon": null
    }
  }
}

Captured from the API examples test suite; ids and timestamps are normalized.

---

DELETE /api/libraries/{id}/connection

Disconnect: revoke the OAuth tokens.

Authentication: Required

Permissions: Requires library:connect

Path Parameters:

Parameter	Type	Description
id	string	Library id or natural id

Response:

Responds 200 with an empty body.

DisconnectDELETE /api/libraries/admin:engineering-drive/connection

Revokes the OAuth tokens and disconnects. Responds 200 with an empty body. Scheduled syncs fail until the library is reconnected.

Response · 200 · no body

Captured from the API examples test suite; ids and timestamps are normalized.

Sync impact

Disconnecting revokes OAuth access. Scheduled syncs fail until the connection is re-established.

---

POST /api/libraries/{id}/_sync

Manually trigger a sync from the connected cloud integration.

Authentication: Required

Permissions: Requires library:sync

Path Parameters:

Parameter	Type	Description
id	string	Library id or natural id

Request Body:

Field	Type	Default	Description
purge	boolean	false	Delete all existing files before syncing
progress	string	-	Progress-tracking identifier

Response:

Runs the sync as a tracked task and responds with the task result. The library must have an active connection first, otherwise the call returns 400 (No Connection has been set up for the Library.).

Long-running

This endpoint may take several minutes for large libraries. Track progress via the progress identifier. It is not exercised in the captured examples because it requires a live provider connection.

---

GET /api/libraries/{id}/account

Get account information for the connected integration.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Library id or natural id

Response:

The connected provider account (driver-specific). Requires an active connection, otherwise it returns 400 prompting you to connect first. Not exercised in the captured examples because it calls the provider.