External API Integration Guide

Comprehensive instructions for integrating your external REST or GraphQL APIs with our platform.

Choose Bots or Agents endpoint

Note that separate API endpoints are in place for bots and agents. For the agents API use this: https://agentic.theblockbrain.ai/docs#description/introduction

What You'll Need

• A REST or GraphQL API service

• OpenAPI 3.0+ specification (JSON or YAML format)

• Secure authentication mechanism

• HTTPS-enabled endpoints

• Tenant Administrator access for setup

Getting Started

Prerequisites

Important: You must be a Tenant Administrator to add external services.

Step 1: Prepare Your API Specification

Your API must be documented using one of the supported specification formats:

• OpenAPI 3.0+ (Recommended - JSON or YAML format)

• GraphQL Schema (SDL format)

Step 2: Choose Authentication Method

Select the appropriate authentication method based on your use case:

• Fixed API Token: For service-to-service authentication

• User Token (Delegated Access): For user-specific data access

Step 3: Configure Security

Ensure your API implements proper security measures including HTTPS, input validation, and access controls.

API Specification Requirements

OpenAPI Specification (Recommended)

Required Elements:

• Format: JSON or YAML

• Version: OpenAPI 3.0+ (3.1 recommended)

• Delivery: Publicly available endpoint URL

Note: Direct file uploads are not supported at this time. Your OpenAPI specification must be accessible via a public URL.

Example OpenAPI 3.1 Structure:

YAMLFullscreenCopy codeopenapi: 3.1.0  
info:  
  title: Your API Name  
  version: 1.0.0  
  description: API description  
servers:  
    - url: https://api.yourcompany.com/v1  
    description: Production server  
paths:  
  /resource:  
    get:  
      summary: Get resource  
      operationId: getResource  
      responses:  
        '200':  
          description: Successful response  
          content:  
            application/json:  
              schema:  
                type: object  
components:  
  securitySchemes:  
    ApiKeyAuth:  
      type: apiKey  
      in: header  
      name: X-API-Key  

Must-Have Requirements:

• Valid OpenAPI 3.0+ standards compliance

• Complete endpoint definitions with operationId fields

• Clear security scheme definitions

• Comprehensive endpoint and parameter descriptions

• Example responses where applicable

GraphQL Schema

Format: SDL (Schema Definition Language)

GraphQLFullscreenCopy codetype Query {  
  getResource(id: ID!): Resource  
}

type Resource {  
  id: ID!  
  name: String!  
  description: String  
}  

---

Authentication Methods

MVP Notice: Currently, only API Key and Basic Authentication are supported. User Token (Delegated Access) is not yet available.

Option 1: API Key

Best for: Service-to-service authentication without user context

How It Works:

1. You provide a long-lived API key

2. We store it encrypted in our system (tenant-based encryption)

3. We include it in the Authorization header for every request

Your Requirements:

• Generate a secure, long-lived API key

• Ensure the key has appropriate permissions

• Provide a key rotation mechanism

• Monitor API key usage

Option 2: Basic Authentication

Best for: APIs that authenticate via username and password credentials

How It Works:

1. You provide a username and password

2. We store the credentials encrypted in our system (tenant-based encryption)

3. We encode them as a Base64 Authorization: Basic <credentials> header on every request

Your Requirements:

• Provide valid username and password credentials

• Ensure credentials have appropriate access permissions

• Implement credential rotation where possible

• Monitor authentication usage

---

Setup Instructions

Step 1: Navigate to Custom Integrations

1. Log in to your tenant admin account

2. Go to Settings → Integrations → Custom Integrations (or Connectors)

3. Click Add New Integration

Step 2: Choose Integration Type

Select one of the following:

• API Integration (for REST/GraphQL APIs)

• MCP Server (for Model Context Protocol servers)

Step 3: Configure Integration Settings

For API Integration

Field	Description	Required
Name	Integration display name	Yes
Base URL	API base endpoint	Yes
OpenAPI Spec	URL to JSON/YAML specification file	Yes
Authorization Method	API Key or Basic Authentication	Yes
API Key	Your API key (if API Key auth)	Conditional
Username	Your username (if Basic Authentication)	Conditional
Password	Your password (if Basic Authentication)	Conditional
Additional Headers	Custom headers (key-value pairs)	No
Endpoint Filtering	Configure which endpoints to expose	Recommended

Note: Direct file upload for the OpenAPI Spec is not currently supported. Provide a publicly accessible URL instead.

For MCP Server

Field	Description	Required
Name	Integration display name	Yes
Base URL	MCP server endpoint	Yes
Transport	SSE or HTTP	Yes
Authorization Method	API Key or Basic Authentication	Yes
API Key	Your API key (if API Key auth)	Conditional
Username	Your username (if Basic Authentication)	Conditional
Password	Your password (if Basic Authentication)	Conditional
Resource Filter	Comma-separated resource URIs (optional)	Recommended
Tool Filter	Comma-separated tool names (optional)	Recommended
Max Tools	Maximum number of tools	No
Max Resources	Maximum number of resources	No

Step 4: Validate Configuration

Our system will automatically:

• Scan and validate your OpenAPI specification (for APIs)

• Test connectivity to your server

• Verify authentication credentials

• List available tools/resources (for MCP)

---

Security Guidelines

Universal Requirements (All Authentication Methods)

Required Security Measures:

• HTTPS Only: All endpoints must use HTTPS

• Input Validation: Sanitize all inputs before processing

• Output Filtering: Remove sensitive data from responses

• Access Control: Implement role-based access control (RBAC)

• Audit Logging: Log all API access with user context

• Data Encryption: Encrypt sensitive data at rest and in transit

• Rate Limiting: Prevent abuse with request throttling

Recommended Additional Security:

• IP whitelisting (contact us for egress IP)

• API gateways for centralized security

• DDoS protection

• Regular security audits

• Incident response plan

---

Validation & Testing

Validation Tools

Before submitting your specification, validate it using:

1. Swagger Editor — Interactive validation

2. OpenAPI Validator — Automated checks

Testing Checklist

• OpenAPI specification passes validation

• All endpoints have proper operationId fields

• Security schemes are correctly defined

• Authentication flow works as expected

• Rate limiting is properly configured

• Error responses are well-documented

---

Agent Assignment

Step 5: Assign to Agent

After successfully configuring your integration, assign it to agents:

1. Navigate to Agent Settings in the admin panel or in the agent selection in a Data Room

2. Select the agent you want to configure

3. Under External APIs, select your newly created integration

4. Save agent configuration

MCP Server Considerations

Tool Design Best Practices:

• Limit the number of tools exposed (recommended: 10–20 maximum)

• Use clear, action-oriented tool names

• Provide comprehensive input schemas

• Handle errors gracefully with descriptive messages

Resource Management:

• Define explicit resource URIs

• Use appropriate MIME types

• Implement efficient caching strategies

Performance:

• Implement timeout handling

• Use pagination for large datasets

• Cache frequently accessed resources

---

Next Steps

1. Prepare your API specification following the requirements above

2. Choose and implement your authentication method (API Key or Basic Authentication)

3. Validate your specification using the recommended tools

4. Test the integration in your development environment

5. Access your tenant admin account to configure the integration

6. Follow the setup instructions to add your service

7. Assign the integration to agents as needed