Integration API Overview

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)

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