Overview

Tip

Just ask your agent. The easiest way to connect APIs is to tell your agent what you need:

• “Connect to the JSONPlaceholder API”
• “Add access to my company’s internal API”
• “Set up the weather API with my API key”

The agent handles configuration, credentials, and validation automatically.

API sources provide a flexible HTTP tool that lets your agents connect to virtually any REST API. If a service has an API, your agent can use it - no MCP server required.

How It Works

When you configure an API source, Craft Agents:

1. Creates a flexible HTTP tool for making requests
2. Handles auth by securely storing and injecting credentials
3. Validates the connection using the test endpoint
4. Enables the agent to make any request to the API’s base URL

The result: your agent can call any endpoint on the configured API.

Configuration

API sources are configured with a JSON file:

{
  "type": "api",
  "name": "My API",
  "tagline": "Description of the API",
  "icon": "https://example.com/icon.png",
  "api": {
    "baseUrl": "https://api.example.com/",
    "testEndpoint": {
      "method": "GET",
      "path": "health"
    },
    "authType": "bearer"
  }
}

Configuration Fields

Field	Required	Description
type	Yes	Must be "api"
name	Yes	Display name for the source
tagline	No	Short description
icon	No	Icon URL, emoji, or local file (auto-discovered: icon.svg, icon.png)
api.baseUrl	Yes	Base URL for all API requests
api.testEndpoint	No	Object to verify connection: { method: "GET" | "POST", path: "endpoint", body?: {}, headers?: {} }
api.authType	Yes	Authentication type (see below)
api.headerName	No	Custom header name for header auth type
api.queryParam	No	Query parameter name for query auth type
api.authScheme	No	Bearer token prefix for bearer auth (default: "Bearer", can be "Token")
api.headerNames	No	Array of header names for multi-header auth (e.g., ["DD-API-KEY", "DD-APPLICATION-KEY"])
api.oauth	No	Generic OAuth 2.0 config block (see OAuth 2.0 section below)
api.renewEndpoint	No	Optional token renewal config for non-OAuth bearer APIs (see Token Renewal section below)

Authentication Types

API sources support six authentication methods:

Bearer Token

{
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "bearer"
  }
}

Sends credentials as Authorization: Bearer {token}.

Header Authentication

{
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "header",
    "headerName": "X-API-Key"
  }
}

Sends credentials in a custom header: X-API-Key: {token}.

Query Parameter Authentication

{
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "query",
    "queryParam": "api_key"
  }
}

Appends credentials as a query parameter: ?api_key={token}.

OAuth 2.0

Two modes: auto-discovery (simplest) and explicit config (for providers without standard metadata).

Auto-discovery (recommended)

If the API supports RFC 9728 (OAuth Protected Resource Metadata), just set authType — endpoints and client registration are handled automatically:

{
  "api": {
    "baseUrl": "https://connect.craft.do/my/api/v1/",
    "authType": "oauth"
  }
}

Craft Agents will hit the base URL, read the WWW-Authenticate header, discover OAuth metadata, dynamically register a client, and start the authorization flow. No oauth config block needed.

Explicit config

For providers that don’t expose standard OAuth metadata (e.g. GitHub, Linear), provide the endpoints manually:

{
  "api": {
    "baseUrl": "https://api.github.com/",
    "authType": "oauth",
    "oauth": {
      "authorizationUrl": "https://github.com/login/oauth/authorize",
      "tokenUrl": "https://github.com/login/oauth/access_token",
      "clientId": "your_client_id",
      "clientSecret": "your_client_secret",
      "scopes": ["repo", "read:user"]
    }
  }
}

Field	Required	Description
oauth.authorizationUrl	Yes	OAuth authorization endpoint
oauth.tokenUrl	Yes	OAuth token exchange endpoint
oauth.clientId	Yes	Your OAuth app’s client ID
oauth.clientSecret	No	Client secret (not required for public PKCE clients)
oauth.scopes	No	Requested OAuth scopes
oauth.audience	No	Auth0-style audience parameter
oauth.extraParams	No	Additional authorization URL params

Full OAuth 2.0 flow with PKCE in both modes. Tokens are automatically refreshed and sent as Authorization: Bearer {token}.

Tip

For Google, Microsoft, and Slack APIs, Craft Agents has built-in OAuth support with predefined scopes — you don’t need to configure the oauth block manually. Just set the appropriate provider field.

No Authentication

{
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "none"
  }
}

For public APIs that don’t require authentication.

Basic Authentication

{
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "basic"
  }
}

Sends credentials as Authorization: Basic {base64(username:password)}.

Multi-Header Authentication

{
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "header",
    "headerNames": ["X-API-KEY", "X-APP-KEY"]
  }
}

Sends multiple credentials as separate headers. Each header name in the array gets its own input field during authentication. All headers are included in every API request.

Tip

Use multi-header authentication when an API requires two or more authentication headers simultaneously. This is common for services that separate identity from authorization, or require both an API key and an application secret.

Common use cases:

• Datadog: DD-API-KEY + DD-APPLICATION-KEY
• APIs with identity + signing keys: Separate API key and secret
• Services with app + user credentials: Application key plus user token

Test Endpoint

The testEndpoint field specifies an endpoint used to verify the connection works. When you test a source, Craft Agents makes a request to this endpoint to confirm:

• The base URL is reachable
• Authentication credentials are valid
• The API responds correctly

Common test endpoints:

API Type	Test Endpoint
Health check	/health
User info	/me, /user
API status	/status, /ping

Tip

Choose a lightweight endpoint that requires authentication. This validates both connectivity and credentials in one request.

Token Renewal (Optional)

For bearer-token APIs that provide their own token renewal endpoint (not OAuth), you can configure automatic token refresh with the optional renewEndpoint field. When the token expires, Craft Agents calls this endpoint to get a fresh token — no manual re-authentication needed.

{
  "api": {
    "baseUrl": "https://api.example.com/",
    "authType": "bearer",
    "renewEndpoint": {
      "path": "auth/refresh",
      "method": "POST",
      "tokenField": "access_token",
      "expiresInField": "expires_in"
    }
  }
}

Field	Required	Default	Description
path	Yes	—	Renew URL — relative path (resolved against baseUrl) or absolute URL
method	No	"POST"	HTTP method ("GET" or "POST")
body	No	—	Request body. Use {{token}} as placeholder for the current access token
headers	No	—	Extra headers. {{token}} substitution applies here too
tokenField	No	"access_token"	JSON field name for the new token in the response
expiresInField	No	"expires_in"	JSON field name for expiry in seconds
fallbackTtlSecs	No	—	Fallback TTL when the response doesn’t include expiry

When body is omitted, the current token is sent via the Authorization header. When body is provided, {{token}} placeholders in string values are replaced with the current token (supports nested objects).

Tip

This is for APIs with custom renewal endpoints, not OAuth. For OAuth-based APIs, use authType: "oauth" instead — tokens are refreshed automatically via the standard OAuth flow.

Why Use API Sources?

• Universal Compatibility

  Any service with a REST API can be integrated.

• Simple Configuration

  Just provide the base URL and auth details.

• Flexible Requests

  The HTTP tool can make any request to the API — JSON bodies by default, with raw body support for plain text, XML, and other content types.

• Secure Credentials

  API keys are stored encrypted, not in config files.

Comparison: MCP vs API Sources

Feature	MCP Sources	API Sources
Setup	Need MCP server URL	Base URL + auth config
Tools	Predefined by server	Flexible HTTP tool
Auth	OAuth or bearer	OAuth, bearer, header, query, basic, none
Best for	Services with MCP support	Any REST API

Use MCP sources when available for richer integration with predefined tools. Use API sources for services without MCP support or when you need flexible HTTP access.

Note

Need Google, Microsoft, or Slack? Craft Agents has built-in OAuth support for these services with predefined scopes. Just ask your agent to “connect Google Calendar” or “add Slack” and it will walk you through the OAuth flow.

Need any other OAuth provider? Use authType: "oauth" with the oauth config block to connect GitHub, Linear, Notion, Spotify, or any other OAuth 2.0 service.

Next Steps

Practical Examples

Real-world examples of API source configurations.