# REST API Source Configuration Options in Craft Agents OSS: A Complete Guide > Explore REST API source configuration options in Craft Agents OSS. Learn about endpoint URLs, authentication, request defaults, and OAuth for seamless API integration. - Repository: [Craft Docs/craft-agents-oss](https://github.com/lukilabs/craft-agents-oss) - Tags: how-to-guide - Published: 2026-04-18 --- **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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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` 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`](https://github.com/lukilabs/craft-agents-oss/blob/main/api-tools.ts) to handle token exchange and refresh. ## Implementation Details and Key Files | File | Role | |------|------| | [`packages/shared/src/sources/types.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/shared/src/sources/types.ts) | Defines `ApiSourceConfig`, `ApiOAuthConfig`, `ApiRenewEndpoint`, and all supporting interfaces. | | [`packages/shared/src/sources/api-tools.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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`](https://github.com/lukilabs/craft-agents-oss/blob/main/apps/electron/src/renderer/components/sources/SourceStatus.tsx) | Handles `testEndpoint` execution and `renewEndpoint` status reporting. | ## Configuration Examples ### Minimal Public API (No Authentication) ```json { "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) ```json { "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) ```json { "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) ```json { "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 ```json { "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": "", "clientSecret": "", "scopes": ["read", "write"] } } } ``` ### Token Renewal Endpoint (Non-OAuth) ```json { "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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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.