Connectors & Integrations

Connectors allow Agents to interact securely with external third-party services and SaaS APIs (such as GitHub, Slack, Notion, PostgreSQL, and custom MCP servers). Skopik manages credential encryption, OAuth 2.0 token refreshes, and tool discovery automatically.

Secure credential vault

Connectors store credentials in Skopik's encrypted integration vault:

Credentials (API tokens, private keys, client secrets) are write-only.
Subsequent reads return redacted profiles and connection health metadata, never sensitive credential strings.
Process sandboxes receive short-lived materialization grants only when executing connector-backed tools.

Create a Connector

Create a Connector by providing its integration type and credentials:

const connector = await skopik.connectors.create({
	name: 'github-org-integration',
	displayName: 'GitHub Organization',
	kind: 'github',
	config: {
		token: process.env.GITHUB_PERSONAL_ACCESS_TOKEN,
		defaultOwner: 'my-org',
	},
})

console.log('Connector created:', connector.connectorId, 'Status:', connector.status)

curl "https://api.skopik.com/api/v1/connectors" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-org-integration",
    "display_name": "GitHub Organization",
    "kind": "github",
    "config": {
      "token": "ghp_...",
      "default_owner": "my-org"
    }
  }'

OAuth 2.0 authorization flow

For services requiring OAuth (e.g. Slack or Google Workspace), initiate the OAuth flow to obtain an authorization URL:

const { authorizeUrl } = await skopik.connectors.startOAuth(connector.connectorId)

// Redirect your user to the consent screen
console.log('Authorize URL:', authorizeUrl)

curl "https://api.skopik.com/api/v1/connectors/$CONNECTOR_ID/oauth/start" \
  -X POST \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Once the user approves access, Skopik's OAuth callback handler securely exchanges the authorization code for encrypted access and refresh tokens.

Test connection & discover tools

Validate connectivity and check tool discovery before attaching a Connector to production Sessions:

const testResult = await skopik.connectors.test(connector.connectorId)

console.log('Connected:', testResult.ok)
console.log('Available tools:', testResult.tools) // e.g. ['mcp__github_create_issue', 'mcp__github_list_prs']

curl "https://api.skopik.com/api/v1/connectors/$CONNECTOR_ID/test" \
  -X POST \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Attach Connectors to a Session

Attach one or more Connectors when opening a Session. The Agent automatically gains access to the Connector's tools:

const session = await skopik.sessions.open({
	agent: agentId,
	connectors: [connector.connectorId],
	prompt: 'List open pull requests in my-org/backend and summarize any pending reviews.',
	permission: 'ask',
})

curl "https://api.skopik.com/api/v1/sessions" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "ag_12345",
    "connectors": ["conn_67890"],
    "prompt": "List open pull requests in my-org/backend and summarize reviews.",
    "permission_mode": "ask"
  }'

You can also update the active Connectors on an existing live Session:

await skopik.sessions.updateConnectors(sessionId, [connector.connectorId, slackConnectorId])

Manage Connectors

// List all connectors
const { data: connectors } = await skopik.connectors.list()

// Fetch connector metadata
const current = await skopik.connectors.get(connector.connectorId)

// Update connector configuration
const updated = await skopik.connectors.update(connector.connectorId, {
	displayName: 'GitHub Organization (Engineering)',
	config: {
		defaultOwner: 'my-engineering-org',
	},
})

// Delete a connector
await skopik.connectors.delete(connector.connectorId)

curl "https://api.skopik.com/api/v1/connectors" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

curl "https://api.skopik.com/api/v1/connectors/$CONNECTOR_ID" \
  -PATCH \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "GitHub Organization (Engineering)"
  }'

curl "https://api.skopik.com/api/v1/connectors/$CONNECTOR_ID" \
  -X DELETE \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

API reference

SDK Method	HTTP Endpoint	Description
`connectors.list()`	`GET /connectors`	List configured Connectors in your organization.
`connectors.create()`	`POST /connectors`	Create a new Connector with encrypted config.
`connectors.get()`	`GET /connectors/{id}`	Read Connector status, health, and discovered tools.
`connectors.update()`	`PATCH /connectors/{id}`	Update Connector name or configuration.
`connectors.delete()`	`DELETE /connectors/{id}`	Delete a Connector.
`connectors.test()`	`POST /connectors/{id}/test`	Test credentials and connectivity.
`connectors.startOAuth()`	`POST /connectors/{id}/oauth/start`	Generate OAuth 2.0 authorization URL.