Understanding Connectors

Connectors define how Traces collects data from platform APIs. This guide covers the connector architecture and configuration.

What is a Connector?

A connector is a structured configuration that tells the worker how to:

• Authenticate with an API
• Call endpoints in the correct order
• Handle pagination to retrieve all data
• Map dependencies between endpoints
• Extract and store collected data

Connector Structure

interface Connector {
  id: string;
  platformName: string;        // e.g., "Slack", "GitHub"
  platformUrl: string;         // Base API URL
  version: string;             // Semantic version (1.0.0)
  endpoints: Endpoint[];       // API endpoints to call
  authConfig: AuthConfig;      // Authentication settings
  rateLimitGlobal: RateLimit;  // Platform-wide rate limit
  headers: Record<string, string>; // Default headers
}

Creating Connectors

There are three ways to create a connector:

1. Automated Generation (Recommended)

From the connectors list, click Generate from API Docs. Provide an API documentation URL or upload a spec file and let AI analyze it:

• Parses OpenAPI 3.x, Swagger 2.0, or Postman collections
• Analyzes endpoints for forensic relevance
• Generates configuration automatically
• Creates a draft for review

See Automated Generation for details.

2. Manual Creation

Build a connector from scratch:

1. From the connectors list, click New Connector
2. Fill in the platform information form (name, base URL, etc.)
3. Save, then add and configure endpoints in the editor
4. Configure authentication
5. Test and publish

3. Duplicate & Modify

Copy an existing connector and customize:

1. In the connectors list, use the Duplicate row action on an existing connector
2. Open the duplicate and modify as needed (its execution phases are cloned too)
3. Publish as a new version

Endpoint Configuration

Each endpoint includes:

Field	Description	Example
path	API endpoint path	/users/{user_id}/messages
method	HTTP method	GET, POST
friendlyName	Human-readable name	"List User Messages"
category	Logical grouping	users, messages, files
order	Execution order	1, 2, 3
enabled	Include in collections	true/false
pagination	Pagination config	See Pagination
dependencies	Dependencies on other endpoints	See Dependencies

Path Templates

Use curly braces for dynamic path segments:

/repos/{owner}/{repo}/commits
/users/{user_id}/channels/{channel_id}/messages

Template values come from:

1. Dependency mappings
2. Collection parameters
3. Credential metadata

Forensic Relevance

Mark endpoints as forensically relevant when they contain:

• User activity data
• Communication records
• Access logs
• File metadata
• Timestamps and audit trails

Authentication

Supported Types

Type	Configuration	Header Sent
Bearer Token	type: "bearer"	Authorization: Bearer <token>
API Key (Header)	type: "api_key", headerName: "X-API-Key"	X-API-Key: <token>
API Key (Query)	type: "api_key", queryParam: "api_key"	?api_key=<token>
Basic Auth	type: "basic"	Authorization: Basic <base64>
OAuth2	type: "oauth2"	Authorization: Bearer <token>
Token Exchange	type: "token_exchange"	Configurable (header or query)

OAuth2 Configuration

{
  "type": "oauth2",
  "tokenPrefix": "Bearer",
  "requiredScopes": ["read:users", "read:messages"],
  "tokenEndpoint": "https://api.example.com/oauth/token",
  "refreshSupported": true
}

Token Exchange

Token exchange lets you configure a token endpoint that Traces calls automatically before each collection to obtain a short-lived access token. Use this for platforms that require you to trade a client credential or authorization code for a bearer token (Atlassian, Salesforce, etc.).

Configure it in Auth Config → Token Exchange:

Field	Description
Token Endpoint URL	Full URL of the token endpoint (supports {{variable_name}} templates)
Method	HTTP method for the token request (POST or GET)
Body Format	Request body encoding: application/json, application/x-www-form-urlencoded, or none
Endpoint Auth	How to authenticate to the token endpoint: basic (client_id/secret in Authorization header), bearer, api_key, or none
Request Body	Grant type, redirect URI, scope, custom fields
Response Mapping	JSON path to the access token in the response (e.g. access_token)
Apply Token As	Where to attach the resulting token: request header (Authorization: Bearer) or query parameter

Static Body Fields

Static body fields are key-value pairs always included in the token request body — typically client_id, client_secret, and redirect_uri. They are stored as part of the connector configuration (not per-analyst credentials).

Authorization Code Flow (OAuth2 with Browser Redirect)

Enable Authorization Code Flow to add a browser-redirect step before token exchange. When an analyst sets up test credentials, they will:

1. Be redirected to the platform's authorization URL
2. Log in and grant permissions
3. Be redirected back with an authorization code
4. Traces exchanges that code for an access token using the token endpoint

Configure the OAuth flow:

Field	Description
Authorization URL	Platform's OAuth authorize endpoint
Additional Params	Extra query params appended to the authorization URL (e.g. audience, prompt)
Callback Code Param	Query param name containing the returned code (default: code)

When Authorization Code Flow is enabled, Endpoint Auth is automatically set to none (the code itself is the credential, placed in the request body).

Direct Token Bypass

Analysts can skip the token exchange flow entirely by entering an access token they already have. The token is stored directly and used as-is, bypassing the token endpoint call.

Input Variables

Input variables let you inject values into endpoint URLs, query parameters, and token endpoint URLs using {{variable_name}} template syntax. They are defined on the connector and apply across all endpoints.

Variable Types

Type	Description	Stored Where
Static	Fixed value stored on the connector	Connector config
Runtime	Prompted when starting each collection	Per collection

Usage

Reference a variable in any URL template using double curly braces:

https://{{base_domain}}/api/v2/users
/orgs/{{org_id}}/repos

Variables are also supported in the Token Endpoint URL field, enabling multi-tenant connectors where the token endpoint URL differs per customer.

Static Variables

Static variables hold a value that never changes. Example: a fixed API version prefix, a shared tenant slug, or the OAuth token endpoint host.

Runtime Variables

Runtime variables have no stored value. When a collection starts, the customer or analyst is prompted to provide the value. A test value can be set on the connector to enable live test requests during connector building — this test value is never published.

Auto-wiring

Set an auto-apply parameter name on a variable to automatically wire it to every endpoint that has a matching parameter name. For example, setting auto-apply = tenant_id wires the variable to every {tenant_id} path segment and every tenant_id query parameter across the connector.

See Reusable Variables for the full guide on extracted and merged variables.

Rate Limiting

Global Rate Limit

Applies to all endpoints:

{
  "rateLimitGlobal": {
    "requests": 1000,
    "windowSeconds": 3600
  }
}

Endpoint Rate Limit

Overrides global for specific endpoint:

{
  "rateLimit": {
    "requests": 10,
    "windowSeconds": 60
  }
}

Headers

Default Headers

Set headers applied to all endpoints:

{
  "headers": {
    "Accept": "application/json",
    "User-Agent": "Traces-Collector/1.0",
    "X-API-Version": "2024-01-01"
  }
}

Endpoint Headers

Override or add headers per endpoint:

{
  "headers": {
    "Accept": "application/vnd.api+json",
    "X-Custom-Scope": "read:messages"
  }
}

Best Practices

Connector Design

1. Start with essential endpoints - Add core data sources first
2. Use descriptive names - "List User Messages" not "GET /messages"
3. Group by category - Consistent categorization aids review
4. Document quirks - Use analyst notes for platform-specific behaviors
5. Version thoughtfully - Coordinate major changes with users

Performance

1. Configure appropriate page sizes - Balance throughput and memory
2. Respect rate limits - Use conservative values initially
3. Order dependencies correctly - Minimize round trips

Maintenance

1. Monitor for API changes - Platforms update frequently
2. Update documentation links - Keep references current
3. Archive old versions - Don't delete, version instead

Next Steps

• Automated Generation
• Endpoint Configuration
• Pagination Reference
• Dependency Mapping