REST API Source Configuration Options in Craft Agents OSS: A Complete Guide

REST API sources in Craft Agents OSS are configured via the ApiSourceConfig interface, which defines options for endpoint URLs, authentication types (Bearer, OAuth, headers, query parameters), request defaults, health checks, and provider-specific OAuth settings for Google, Slack, and Microsoft.

The lukilabs/craft-agents-oss repository models external REST APIs as sources of type api. All configuration for these integrations is centralized in the ApiSourceConfig interface defined in packages/shared/src/sources/types.ts. This system allows agents to dynamically discover and invoke API endpoints while handling authentication, token renewal, and health checks automatically.

Core Configuration Schema

Every REST API source is defined by the ApiSourceConfig interface located in packages/shared/src/sources/types.ts. This interface specifies the complete set of properties used by the agent runtime to construct requests, manage credentials, and validate connectivity.

Endpoint Configuration

The baseUrl property is the only required field. It defines the root URL of the REST service (e.g., https://api.github.com). This value is prepended to every request path and is also used for service inference via helper functions like inferGoogleServiceFromUrl, inferSlackServiceFromUrl, and inferMicrosoftServiceFromUrl.

Authentication Types

The authType field accepts an ApiAuthType enum value: 'bearer', 'header', 'query', 'basic', 'oauth', or 'none'. This declaration determines which subsequent authentication fields are consulted when building requests in api-tools.ts.

Bearer Token Authentication ('bearer'):

• authScheme: Optional string prefix for the Authorization header (default "Bearer"; can be "Token" for GitHub).

Header-Based Authentication ('header'):

• headerName: Single header name for simple key-based auth (e.g., "X-API-Key").
• headerNames: Array of headers for services requiring multiple keys (e.g., ["DD-API-KEY", "DD-APPLICATION-KEY"] for Datadog).

Query Parameter Authentication ('query'):

• queryParam: The query-string key used to transmit the token (e.g., "api_key").

Request Defaults

The defaultHeaders property accepts a Record<string, string> object containing static headers sent with every request. Common examples include "Accept": "application/json" or custom "Content-Type" values. These are merged with per-request headers and credential-store headers at runtime.

Health Check and Token Renewal

testEndpoint (ApiTestEndpoint): Defines a lightweight endpoint used by the UI to verify connectivity. It includes method, path, and optional body/headers. When a user clicks Test Connection, this configuration is executed and results are stored in connectionStatus.

renewEndpoint (ApiRenewEndpoint): Configures non-OAuth token renewal flows. It specifies the path, method, body template (with {{token}} interpolation), response field mapping (tokenField, expiresInField), and custom headers. This is invoked automatically when isRefreshableSource detects an expired token.

Provider-Specific OAuth Configuration

When authType is set to 'oauth', the platform supports provider-specific shortcuts for Google, Slack, and Microsoft, alongside a generic OAuth configuration.

Google Services

• googleService: Pre-selected service enum (gmail, calendar, drive, etc.) that drives OAuth scope generation.
• googleScopes: Custom OAuth scopes that override the preset service list.
• googleOAuthClientId / googleOAuthClientSecret: User-provided OAuth client credentials for self-hosted Google Cloud projects.

Slack Services

• slackService: Pre-selected Slack service (messaging, channels, files, etc.) for scope selection.
• slackUserScopes: Custom Slack scopes overriding the preset service.

Microsoft Graph

• microsoftService: Pre-selected Microsoft Graph service (outlook, onedrive, teams, etc.).
• microsoftScopes: Custom Microsoft OAuth scopes.

Generic OAuth Configuration

For OAuth providers not covered by the built-in shortcuts, the oauth field accepts an ApiOAuthConfig object:

• authorizationUrl: The OAuth 2.0 authorization endpoint.
• tokenUrl: The token exchange endpoint.
• clientId / clientSecret: Application credentials.
• scopes: Array of permission scopes.
• Extra parameters: Additional query parameters for the authorization URL.

This configuration is consumed by the generic OAuth flow in api-tools.ts to handle token exchange and refresh.

Implementation Details and Key Files

File	Role
packages/shared/src/sources/types.ts	Defines ApiSourceConfig, ApiOAuthConfig, ApiRenewEndpoint, and all supporting interfaces.
packages/shared/src/sources/api-tools.ts	Consumes the configuration to build dynamic request functions and handle auth flows.
apps/electron/src/renderer/components/sources/SourceEditor.tsx	UI component exposing configuration fields to users when adding or editing sources.
apps/electron/src/renderer/components/sources/SourceStatus.tsx	Handles testEndpoint execution and renewEndpoint status reporting.

Configuration Examples

Minimal Public API (No Authentication)

{
  "id": "public-json-placeholder",
  "name": "JSONPlaceholder",
  "slug": "json-placeholder",
  "provider": "jsonplaceholder",
  "type": "api",
  "enabled": true,
  "api": {
    "baseUrl": "https://jsonplaceholder.typicode.com",
    "authType": "none",
    "defaultHeaders": {
      "Accept": "application/json"
    }
  }
}

Bearer Token Authentication (GitHub)

{
  "id": "github-api",
  "name": "GitHub",
  "slug": "github",
  "provider": "github",
  "type": "api",
  "enabled": true,
  "api": {
    "baseUrl": "https://api.github.com",
    "authType": "bearer",
    "authScheme": "Bearer",
    "defaultHeaders": {
      "Accept": "application/vnd.github+json"
    }
  }
}

Multi-Header Authentication (Datadog)

{
  "id": "datadog-metrics",
  "name": "Datadog Metrics",
  "slug": "datadog-metrics",
  "provider": "datadog",
  "type": "api",
  "enabled": true,
  "api": {
    "baseUrl": "https://api.datadoghq.com/api/v1",
    "authType": "header",
    "headerNames": ["DD-API-KEY", "DD-APPLICATION-KEY"],
    "defaultHeaders": {
      "Content-Type": "application/json"
    }
  }
}

Google OAuth with Custom Scopes (Gmail)

{
  "id": "gmail-api",
  "name": "Gmail",
  "slug": "gmail",
  "provider": "google",
  "type": "api",
  "enabled": true,
  "api": {
    "baseUrl": "https://gmail.googleapis.com",
    "authType": "oauth",
    "googleService": "gmail",
    "googleScopes": [
      "https://www.googleapis.com/auth/gmail.readonly",
      "https://www.googleapis.com/auth/gmail.send"
    ]
  }
}

Generic OAuth for Custom Services

{
  "id": "custom-oauth",
  "name": "My Service",
  "slug": "my-service",
  "provider": "myservice",
  "type": "api",
  "enabled": true,
  "api": {
    "baseUrl": "https://api.myservice.com/v2",
    "authType": "oauth",
    "oauth": {
      "authorizationUrl": "https://login.myservice.com/oauth/authorize",
      "tokenUrl": "https://login.myservice.com/oauth/token",
      "clientId": "<YOUR_CLIENT_ID>",
      "clientSecret": "<YOUR_CLIENT_SECRET>",
      "scopes": ["read", "write"]
    }
  }
}

Token Renewal Endpoint (Non-OAuth)

{
  "id": "example-renew",
  "name": "Example API",
  "slug": "example-api",
  "provider": "example",
  "type": "api",
  "enabled": true,
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "bearer",
    "renewEndpoint": {
      "path": "/auth/refresh",
      "method": "POST",
      "body": { "refresh_token": "{{token}}" },
      "tokenField": "access_token",
      "expiresInField": "expires_in"
    }
  }
}

Summary

• REST API source configuration options in Craft Agents OSS are defined by the ApiSourceConfig interface in packages/shared/src/sources/types.ts.
• The baseUrl field is required and serves as the root for all API requests, while authType determines which authentication fields are active.
• Authentication supports Bearer tokens, header-based keys (single or multiple), query parameters, Basic auth, and OAuth 2.0 (generic or provider-specific).
• Provider-specific shortcuts exist for Google, Slack, and Microsoft services, allowing pre-selected scopes and OAuth client configurations.
• The testEndpoint validates connectivity during setup, while renewEndpoint handles non-OAuth token refresh flows automatically.
• Configuration is consumed by api-tools.ts to generate dynamic API tools that agents invoke at runtime.

Frequently Asked Questions

What is the minimum required configuration for a REST API source?

The only strictly required field is baseUrl, which defines the root endpoint of the REST service. For public APIs that require no authentication, setting authType to "none" and providing any necessary defaultHeaders (such as Accept: application/json) is sufficient to establish a working source.

How does Craft Agents OSS handle OAuth authentication for REST APIs?

When authType is set to "oauth", the platform supports both provider-specific and generic OAuth flows. For Google, Slack, or Microsoft, you can use shortcut fields like googleService or slackService to automatically select appropriate scopes. For other providers, the oauth object accepts authorizationUrl, tokenUrl, clientId, clientSecret, and custom scopes. The runtime in api-tools.ts handles token exchange and refresh automatically.

What is the difference between testEndpoint and renewEndpoint?

The testEndpoint (ApiTestEndpoint) configures a lightweight probe—typically a GET request to a status or user info endpoint—that the UI executes when a user clicks Test Connection. It validates that credentials and networking are correctly configured. The renewEndpoint (ApiRenewEndpoint), conversely, configures a non-OAuth token refresh mechanism. It specifies the path, HTTP method, request body template (with {{token}} interpolation), and response field mappings (tokenField, expiresInField) used by isRefreshableSource to automatically rotate expired credentials.

Where are the TypeScript interfaces for REST API source configuration defined?

All core type definitions— including ApiSourceConfig, ApiAuthType, ApiOAuthConfig, ApiTestEndpoint, and ApiRenewEndpoint—are located in packages/shared/src/sources/types.ts. This file serves as the source of truth for the shape of REST API configurations across the entire Craft Agents OSS platform.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}