SourceService API

Package: dodil.k3.source.v1

SourceService manages data sources and the credentials used to access them.

What It Is For

Create and manage source connectors in a bucket.
Store credentials (OAuth2, API keys, PAT, service account, access key).
Run OAuth authorization and token exchange flows.

Endpoint Map

Sources

gRPC method	HTTP route
`CreateSource`	`POST /:bucket/sources`
`ListSources`	`GET /:bucket/sources`
`GetSource`	`GET /:bucket/sources/:source_id`
`UpdateSource`	`PATCH /:bucket/sources/:source_id`
`DeleteSource`	`DELETE /:bucket/sources/:source_id`

Credentials

gRPC method	HTTP route
`StoreCredential`	`POST /admin/credentials`
`ListCredentials`	`GET /admin/credentials`
`GetCredential`	`GET /admin/credentials/:credential_id`
`DeleteCredential`	`DELETE /admin/credentials/:credential_id`
`ValidateCredential`	`POST /admin/credentials/:credential_id/validate`
`RefreshOAuthToken`	`POST /admin/credentials/:credential_id/refresh`

OAuth

gRPC method	HTTP route
`GetOAuthUrl`	`POST /admin/oauth/authorize`
`ExchangeOAuthCode`	`POST /admin/oauth/token`

Key Arguments

Create source

Field	Type	Required	Purpose
`bucket`	string	yes	Bucket that owns the source
`provider`	enum	yes	Source provider type
`name`	string	yes	User-facing source name
`description`	string	no	Description for operators
`root_path`	string	no	Folder/prefix to crawl
`provider_account`	string	no	Provider-specific account locator
`sync_interval_seconds`	int64	no	Auto-sync cadence (`0` manual only)
`enabled`	bool	no	Source active status

Supported providers include:

SOURCE_PROVIDER_INTERNAL_S3
SOURCE_PROVIDER_GOOGLE_DRIVE
SOURCE_PROVIDER_SHAREPOINT
SOURCE_PROVIDER_CONFLUENCE
SOURCE_PROVIDER_GITHUB

Store credential

Field	Type	Required	Purpose
`provider`	enum	yes	Credential provider
`credential_type`	enum	yes	OAuth2/API key/PAT/access key/service account
`display_name`	string	yes	Human-readable identifier
`source_id`	string	no	Optional source binding
`is_primary`	bool	no	Mark as primary credential
`credential_data`	oneof	yes	Provider-specific secret payload

OAuth requests

Field	Type	Required	Purpose
`provider`	enum	yes	OAuth provider
`redirect_uri`	string	no	Callback URI
`scopes`	string[]	no	Requested scopes
`state`	string	no	CSRF correlation token

ExchangeOAuthCode adds:

code (required)
optional source_id
optional display_name

Examples

Create a Google Drive source


curl -sS -X POST "https://k3.dev.dodil.io/kb-prod/sources" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "kb-prod",
    "provider": "SOURCE_PROVIDER_GOOGLE_DRIVE",
    "name": "finance-drive",
    "root_path": "/Q2",
    "provider_account": "drive-id-123",
    "sync_interval_seconds": 3600,
    "enabled": true
  }'

Store an access-key credential


curl -sS -X POST "https://k3.dev.dodil.io/admin/credentials" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "SOURCE_PROVIDER_INTERNAL_S3",
    "credential_type": "CREDENTIAL_TYPE_ACCESS_KEY",
    "display_name": "ceph-readwrite",
    "access_key": {
      "access_key_id": "AKIA...",
      "secret_access_key": "secret",
      "region": "us-east-1",
      "endpoint": "https://s3.internal"
    }
  }'

Start OAuth and exchange code


curl -sS -X POST "https://k3.dev.dodil.io/admin/oauth/authorize" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "SOURCE_PROVIDER_GOOGLE_DRIVE",
    "redirect_uri": "https://app.example.com/k3/oauth/callback",
    "scopes": ["drive.readonly"],
    "state": "req-123"
  }'
 
curl -sS -X POST "https://k3.dev.dodil.io/admin/oauth/token" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "SOURCE_PROVIDER_GOOGLE_DRIVE",
    "code": "<oauth_code>",
    "redirect_uri": "https://app.example.com/k3/oauth/callback",
    "display_name": "gdrive-main"
  }'

Common Use Cases

Onboard a new external repository and schedule periodic sync.
Rotate or validate credentials without recreating the source.
Build provider-specific onboarding UX around OAuth URL and token exchange.

Next: PipelineService