Skip to main content

Connections

A connection is a stored OAuth grant to an external provider (Google or Atlassian). You create a connection once — the user approves access in the provider's browser consent screen — and then reference it from any number of authenticated sources by connection_id. VectorAmp resolves and refreshes the credentials server-side at ingest time, so sources and schedules backed by a connection keep working without re-consent. All connection endpoints live under the unprefixed /connections namespace at the gateway root.

info

All connection and source IDs are UUIDs.

Two ways to authenticate a source

Connections are the interactive path. If you want a fully headless setup (servers, CI) with no browser consent, use a service account instead — see Authenticating sources. This page covers the connection (OAuth grant) path and the end-to-end authenticated Google Drive walkthrough.

Connection Object​

FieldTypeDescription
idUUIDUnique connection identifier
providerstringOAuth provider (google or atlassian)
account_emailstring | nullEmail of the account that granted access (null until connected)
statusstringOne of pending, connected, error, revoked
created_atstringISO 8601 timestamp
Redaction

Connections never expose access or refresh tokens. Tokens are stored encrypted and used only server-side at ingest time.

List Connections​

GET /connections

Returns the connections for the authenticated organization.

Query Parameters​

NameTypeRequiredDescription
providerstringFilter by provider: google or atlassian
curl "https://api.vectoramp.com/connections?provider=google" \
  -H "X-API-Key: vsk_<64hex>"

Create Connection​

POST /connections

Starts a new OAuth grant. The response includes an authorization_url. Open it in a browser, approve access, then poll Get Connection until status is connected.

Request Body​

NameTypeRequiredDescription
providerstring✅google or atlassian
source_typestringThe source type the connection is for (e.g. gdrive, gcs, confluence, jira). Lets VectorAmp request the right OAuth scopes
curl -X POST https://api.vectoramp.com/connections \
  -H "X-API-Key: vsk_<64hex>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "source_type": "gdrive"
  }'
Completing the grant

Open authorization_url in a browser and approve access. The connection stays pending until the user finishes consent; then it flips to connected and account_email is populated. Poll Get Connection to detect the transition.

Get Connection​

GET /connections/:connectionId

Returns a single connection object. Poll this after Create Connection until status is connected (or error).

ParameterTypeInDescription
connectionIdUUIDpathConnection identifier
curl https://api.vectoramp.com/connections/d1e2f3a4-b5c6-7890-abcd-ef0123456789 \
  -H "X-API-Key: vsk_<64hex>"

Delete Connection​

DELETE /connections/:connectionId

Revokes and deletes the connection. Sources that reference it by connection_id will fail to authenticate on their next run, so repoint or delete those sources first.

curl -X DELETE https://api.vectoramp.com/connections/d1e2f3a4-b5c6-7890-abcd-ef0123456789 \
  -H "X-API-Key: vsk_<64hex>"

Walkthrough: authenticated Google Drive​

There are two supported ways to ingest a private Google Drive folder. Pick by whether a person can complete a one-time browser consent.

Path A — Service account (fully headless)​

Best for servers, CI, and automation. No browser, no consent screen.

  1. Create a Google service account and download its JSON key.
  2. Share the target Drive folder with the service account's client_email.
  3. Create the source with the JSON in config.service_account_json:
curl -X POST https://api.vectoramp.com/ingestion/sources \
  -H "X-API-Key: vsk_<64hex>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "gdrive",
    "name": "Drive (service account)",
    "config": {
      "folder_ids": ["1AbC2dEf3GhI"],
      "auth_mode": "service_account",
      "service_account_json": {
        "type": "service_account",
        "client_email": "ingest@my-project.iam.gserviceaccount.com",
        "private_key": "-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----\n",
        "project_id": "my-project"
      }
    }
  }'
  1. Start a job (or attach a schedule) against the returned source_id.

Path B — Connection (interactive once, reusable)​

Best when a person can grant access once in the browser; the grant is then reused by every source that references it — including scheduled syncs.

# 1. Start the OAuth grant.
curl -X POST https://api.vectoramp.com/connections \
  -H "X-API-Key: vsk_<64hex>" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "google", "source_type": "gdrive" }'
# -> { "id": "d1e2f3a4-…", "status": "pending", "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?…" }

# 2. Open authorization_url in a browser and approve access.

# 3. Poll until the connection is connected.
curl https://api.vectoramp.com/connections/d1e2f3a4-b5c6-7890-abcd-ef0123456789 \
  -H "X-API-Key: vsk_<64hex>"
# -> { "id": "d1e2f3a4-…", "status": "connected", "account_email": "drive-bot@example.com" }

# 4. Create the source referencing the connection.
curl -X POST https://api.vectoramp.com/ingestion/sources \
  -H "X-API-Key: vsk_<64hex>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "gdrive",
    "name": "Drive (connection)",
    "config": {
      "folder_ids": ["1AbC2dEf3GhI"],
      "connection_id": "d1e2f3a4-b5c6-7890-abcd-ef0123456789"
    }
  }'

# 5. Start a job against the returned source_id.
curl -X POST https://api.vectoramp.com/ingestion/jobs \
  -H "X-API-Key: vsk_<64hex>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "dataset_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Because the credentials are refreshed server-side from the connection at ingest time, the same connection_id works for gdrive, gcs, confluence, and jira sources, and keeps scheduled jobs running without re-consent.