Integration API Overview

Looking for the product view?

The Help Center explains this surface as users see it: Integrations.

The Informer Integration API provides endpoints for managing OAuth-based integrations with external services like Google Drive, OneDrive, SharePoint, Dropbox, and custom OAuth providers. Integrations enable secure connections to third-party services with automatic token refresh and account management. All routes are prefixed with /api.

Features

• CRUD Operations - Create, read, update, and delete integrations
• OAuth 2.0 Flow - Connect and authorize with external services
• Token Management - Automatic access token refresh
• Connection Modes - Per-user or shared connections
• Auth Types - OAuth2, API key, basic auth, bearer tokens
• Ownership & Sharing - Team-based ownership with principal-level sharing and access control
• Custom Headers - Per-integration custom headers with variable expansion (e.g., ${user.email}, ${tenant.id})
• Directory Previews - Preview available directories before connecting
• Icon Management - Upload custom integration icons
• Request Proxying - Proxy authenticated requests through integrations

Integration Types

Integrations support multiple authentication methods:

Auth Type	Description
oauth2	OAuth 2.0 authorization code flow
apikey	API key authentication (header or query param)
basic	HTTP Basic authentication
bearer	Bearer token authentication

Connection Modes

Integrations can be configured in two modes:

Mode	Description
per-user	Each user maintains their own connection (default)
shared	Single shared connection for all users (e.g., service accounts)

Integrations embedded in a Datasource

A Datasource whose driver supports it can authenticate with an Integration's access token: either an existing Integration (integrationId) or a one-off defined inside the Datasource (integration), see the Datasource API. An embedded Integration has embedded: true and a datasourceId, is always API type and shared mode, is owned by the Datasource's owner, never appears in GET /api/integrations or GET /api/integrations-list, cannot be chosen by another Datasource, and cannot be deleted through this API; it goes with its Datasource. Its definition is read and edited through the Datasource's connection, and it is connected through its own inf:connect link like any shared-mode Integration.

Authentication

All Integration API endpoints require authentication via session cookies or API tokens. Most endpoints verify integration permissions before allowing access.

Common Permission Patterns

• Read access - View integration configuration (requires ownership or superuser)
• Write permission - Required for integration:write (create, update, delete)
• Delete permission - Required for integration:delete (remove integration)

OAuth 2.0 Flow

The standard OAuth workflow for integrations:

1. Create integration - POST /api/integrations with OAuth config
2. Initiate OAuth - GET /api/integrations/{id}/connect redirects to provider
3. OAuth callback - User authorizes, provider redirects to GET /oauth2/callback
4. Connection created - Access tokens stored securely, integration is ready

OAuth Configuration

Required fields for OAuth integrations:

Field	Description
authUri	Authorization endpoint (e.g., https://accounts.google.com/o/oauth2/v2/auth)
tokenUri	Token endpoint (e.g., https://oauth2.googleapis.com/token)
clientId	OAuth client ID
clientSecret	OAuth client secret (encrypted at rest)
scope	Space-separated scopes (e.g., https://www.googleapis.com/auth/drive.readonly)
apiBaseUri	Base URL for API requests

Error Responses

Standard HTTP status codes:

• 200 - Success
• 201 - Created (resource created successfully)
• 204 - No Content (successful delete)
• 302 - Redirect (OAuth flow)
• 400 - Bad request (validation error)
• 403 - Forbidden (insufficient permissions)
• 404 - Resource not found
• 500 - Internal server error

Ownership Model

Integrations use a team-based ownership model:

• Owner: Each integration has an ownerId that can be a user or team principal
• Natural ID: Integrations are addressed as ownerId:slug (e.g., admin:google-drive)
• Sharing: Integrations can be shared with other principals via the sharing API, with configurable access levels
• Read Access: Non-superusers can only see integrations they own or that have been shared with them

Next Steps

Explore the specific endpoint categories:

• Core CRUD - Basic integration operations
• OAuth Connections - OAuth flow and connection management
• Directory Previews - Preview external directories
• Templates - Integration templates
• Provision - Auto-provision drive integrations
• Icon Registry - Service icon auto-matching
• Sharing & Ownership - Owner management and share permissions