# External API Integration Guide
#### **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:**
```yaml
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)**
```graphql
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 ` 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**](https://editor.swagger.io/) — Interactive validation
2. [**OpenAPI Validator**](https://github.com/openapi-library/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
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.en.theblockbrain.ai/for-admins/external-api-integration-guide.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.