Enkrypt Secure MCP Gateway REST API Reference

May 11, 2026 ยท View on GitHub

This document provides comprehensive documentation for the REST API endpoints that expose all CLI functionality for the Enkrypt Secure MCP Gateway.

Table of Contents

  1. Getting Started

  2. Authentication

  3. API Endpoints

  4. Error Handling

  5. Examples

Getting Started

Starting the API Server

You can start the REST API server using the CLI:


# Start with default settings (host: 0.0.0.0, port: 8001)
secure-mcp-gateway system start-api

# Start with custom host and port
python cli.py system start-api --host 127.0.0.1 --port 9000

# Start with auto-reload for development
python cli.py system start-api --reload

API Documentation

Once the server is running, you can access:

  • Interactive API Documentation: http://localhost:8001/docs

  • ReDoc Documentation: http://localhost:8001/redoc

  • OpenAPI Schema: http://localhost:8001/openapi.json

Authentication

All API endpoints require authentication using an API key. Include the API key in the Authorization header:

Authorization: Bearer <your_api_key>

Getting an API Key

  1. Create a user: POST /api/v1/users

  2. Create a project: POST /api/v1/projects

  3. Add user to project: POST /api/v1/projects/{project_id}/users

  4. Generate API key: POST /api/v1/users/{user_id}/api-keys

API Endpoints

Configuration Management

List All Configurations

GET /api/v1/configs

Response:

{
  "message": "Configurations retrieved successfully",
  "data": [
    {
      "mcp_config_id": "uuid",
      "mcp_config_name": "My Config",
      "servers": 2,
      "used_by_projects": [...]
    }
  ]
}

Create Configuration

POST /api/v1/configs
Content-Type: application/json

{
  "config_name": "My New Config"
}

Get Configuration

GET /api/v1/configs/{config_identifier}

Update Configuration Name

PUT /api/v1/configs/{config_identifier}/rename
Content-Type: application/json

{
  "new_name": "Updated Config Name"
}

Delete Configuration

DELETE /api/v1/configs/{config_identifier}

Copy Configuration

POST /api/v1/configs/copy
Content-Type: application/json

{
  "source_config": "source_config_name_or_id",
  "target_config": "new_config_name"
}

List Servers in Configuration

GET /api/v1/configs/{config_identifier}/servers

Add Server to Configuration

POST /api/v1/configs/{config_identifier}/servers
Content-Type: application/json

{
  "server_name": "my_server",
  "server_command": "python",
  "args": ["/path/to/server.py"],
  "env": {"ENV_VAR": "value"},
  "tools": {},
  "description": "My MCP Server",
  "input_guardrails_config": {
    "enabled": true,
    "guardrail_name": "Sample Policy"
  },
  "output_guardrails_config": {
    "enabled": true,
    "guardrail_name": "Sample Policy"
  }
}

Update Server in Configuration

PUT /api/v1/configs/{config_identifier}/servers/{server_name}
Content-Type: application/json

{
  "server_command": "python3",
  "args": ["/new/path/to/server.py"],
  "description": "Updated description"
}

Remove Server from Configuration

DELETE /api/v1/configs/{config_identifier}/servers/{server_name}

Remove All Servers from Configuration

DELETE /api/v1/configs/{config_identifier}/servers

Validate Configuration

POST /api/v1/configs/{config_identifier}/validate

Export Configuration

POST /api/v1/configs/{config_identifier}/export
Content-Type: application/json

{
  "output_file": "/path/to/export.json"
}

Import Configuration

POST /api/v1/configs/import
Content-Type: application/json

{
  "input_file": "/path/to/import.json",
  "config_name": "Imported Config"
}

Search Configurations

POST /api/v1/configs/search
Content-Type: application/json

{
  "search_term": "search_query"
}

Update Server Input Guardrails

PUT /api/v1/configs/{config_identifier}/servers/{server_name}/input-guardrails
Content-Type: application/json

{
  "policy_file": "/path/to/policy.json",
  "policy": {
    "enabled": true,
    "guardrail_name": "Input Guardrail Policy",
    "additional_config": {
      "pii_redaction": true
    },
    "block": ["policy_violation", "injection_attack"]
  }
}

Update Server Output Guardrails

PUT /api/v1/configs/{config_identifier}/servers/{server_name}/output-guardrails
Content-Type: application/json

{
  "policy_file": "/path/to/policy.json",
  "policy": {
    "enabled": true,
    "guardrail_name": "Output Guardrail Policy",
    "additional_config": {
      "pii_redaction": true
    },
    "block": ["policy_violation", "injection_attack"]
  }
}

Update Server Guardrails (Both)

PUT /api/v1/configs/{config_identifier}/servers/{server_name}/guardrails
Content-Type: application/json

{
  "input_policy_file": "/path/to/input_policy.json",
  "input_policy": {
    "enabled": true,
    "guardrail_name": "Input Guardrail Policy"
  },
  "output_policy_file": "/path/to/output_policy.json",
  "output_policy": {
    "enabled": true,
    "guardrail_name": "Output Guardrail Policy"
  }
}

Project Management

List All Projects

GET /api/v1/projects

Create Project

POST /api/v1/projects
Content-Type: application/json

{
  "project_name": "My Project"
}

Get Project

GET /api/v1/projects/{project_identifier}

Delete Project

DELETE /api/v1/projects/{project_identifier}

Assign Configuration to Project

POST /api/v1/projects/{project_identifier}/assign-config
Content-Type: application/json

{
  "config_name": "config_name_or_id"
}

Unassign Configuration from Project

POST /api/v1/projects/{project_identifier}/unassign-config

Get Project Configuration

GET /api/v1/projects/{project_identifier}/config

List Project Users

GET /api/v1/projects/{project_identifier}/users

Add User to Project

POST /api/v1/projects/{project_identifier}/users
Content-Type: application/json

{
  "email": "user@example.com"
}

Remove User from Project

DELETE /api/v1/projects/{project_identifier}/users/{user_identifier}

Remove All Users from Project

DELETE /api/v1/projects/{project_identifier}/users

Export Project

POST /api/v1/projects/{project_identifier}/export
Content-Type: application/json

{
  "output_file": "/path/to/project_export.json"
}

Search Projects

POST /api/v1/projects/search
Content-Type: application/json

{
  "search_term": "search_query"
}

User Management

List All Users

GET /api/v1/users

Create User

POST /api/v1/users
Content-Type: application/json

{
  "email": "user@example.com"
}

Get User

GET /api/v1/users/{user_identifier}

Update User

PUT /api/v1/users/{user_identifier}
Content-Type: application/json

{
  "new_email": "newemail@example.com"
}

Delete User

DELETE /api/v1/users/{user_identifier}
Content-Type: application/json

{
  "force": false
}

List User Projects

GET /api/v1/users/{user_identifier}/projects

Generate API Key for User

POST /api/v1/users/{user_identifier}/api-keys
Content-Type: application/json

{
  "project_name": "project_name_or_id"
}

List User API Keys

GET /api/v1/users/{user_identifier}/api-keys?project_identifier=optional_project_id

Delete All User API Keys

DELETE /api/v1/users/{user_identifier}/api-keys

List All API Keys

GET /api/v1/api-keys

Get API Key Details

GET /api/v1/api-keys/{api_key}

Rotate API Key

POST /api/v1/api-keys/rotate
Content-Type: application/json

{
  "api_key": "old_api_key"
}

Disable API Key

POST /api/v1/api-keys/{api_key}/disable

Enable API Key

POST /api/v1/api-keys/{api_key}/enable

Delete API Key

DELETE /api/v1/api-keys/{api_key}

Search Users

POST /api/v1/users/search
Content-Type: application/json

{
  "search_term": "search_query"
}

System Operations

Health Check

GET /api/v1/system/health

System Backup

POST /api/v1/system/backup
Content-Type: application/json

{
  "output_file": "/path/to/backup.json"
}

System Restore

POST /api/v1/system/restore
Content-Type: application/json

{
  "input_file": "/path/to/backup.json"
}

System Reset

POST /api/v1/system/reset
Content-Type: application/json

{
  "confirm": true
}

Settings

Set Enkrypt API Key

PUT /api/v1/settings/enkrypt-api-key
Content-Type: application/json

{
  "api_key": "your-enkrypt-api-key"
}

Get Enkrypt API Key

GET /api/v1/settings/enkrypt-api-key

Configure Telemetry

PUT /api/v1/settings/telemetry
Content-Type: application/json

{
  "enabled": true,
  "url": "http://localhost:4317",
  "insecure": true
}

Error Handling

The API uses standard HTTP status codes and returns error responses in the following format:

{
  "error": "Error type",
  "detail": "Detailed error message",
  "timestamp": "2024-01-01T00:00:00"
}

Common Status Codes

  • 200 OK - Request successful

  • 201 Created - Resource created successfully

  • 400 Bad Request - Invalid request data

  • 401 Unauthorized - Invalid or missing API key

  • 404 Not Found - Resource not found

  • 500 Internal Server Error - Server error

Examples

Complete Workflow Example

Here's a complete example of creating a configuration, project, user, and API key:


# 1. Create a user
curl -X POST "http://localhost:8001/api/v1/users" \
  -H "Authorization: Bearer <admin_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "developer@example.com"}'

# Response: {"message": "User created successfully", "data": {"user_id": "uuid", "email": "developer@example.com"}}

# 2. Create a project
curl -X POST "http://localhost:8001/api/v1/projects" \
  -H "Authorization: Bearer <admin_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"project_name": "Development Project"}'

# Response: {"message": "Project created successfully", "data": {"project_id": "uuid", "project_name": "Development Project"}}

# 3. Add user to project
curl -X POST "http://localhost:8001/api/v1/projects/{project_id}/users" \
  -H "Authorization: Bearer <admin_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "developer@example.com"}'

# 4. Create a configuration
curl -X POST "http://localhost:8001/api/v1/configs" \
  -H "Authorization: Bearer <admin_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"config_name": "Development Config"}'

# 5. Add server to configuration
curl -X POST "http://localhost:8001/api/v1/configs/{config_id}/servers" \
  -H "Authorization: Bearer <admin_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "github_server",
    "server_command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "description": "GitHub MCP Server"
  }'

# 6. Assign configuration to project
curl -X POST "http://localhost:8001/api/v1/projects/{project_id}/assign-config" \
  -H "Authorization: Bearer <admin_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"config_name": "Development Config"}'

# 7. Generate API key for user
curl -X POST "http://localhost:8001/api/v1/users/{user_id}/api-keys" \
  -H "Authorization: Bearer <admin_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"project_name": "Development Project"}'

# Response: {"message": "API key generated successfully", "data": {"api_key": "generated_api_key"}}

Using the Generated API Key

Once you have an API key, you can use it to make authenticated requests:


# List configurations using the generated API key
curl -X GET "http://localhost:8001/api/v1/configs" \
  -H "Authorization: Bearer <generated_api_key>"

# List projects
curl -X GET "http://localhost:8001/api/v1/projects" \
  -H "Authorization: Bearer <generated_api_key>"

Integration Examples

Python Client Example

import requests

class EnkryptGatewayAPI:
    def __init__(self, base_url="http://localhost:8001", api_key=None):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def list_configs(self):
        response = requests.get(f"{self.base_url}/api/v1/configs", headers=self.headers)
        return response.json()

    def create_config(self, config_name):
        data = {"config_name": config_name}
        response = requests.post(f"{self.base_url}/api/v1/configs",
                               headers=self.headers, json=data)
        return response.json()

    def create_user(self, email):
        data = {"email": email}
        response = requests.post(f"{self.base_url}/api/v1/users",
                               headers=self.headers, json=data)
        return response.json()

# Usage
api = EnkryptGatewayAPI(api_key="your_api_key")
configs = api.list_configs()
print(configs)

JavaScript/Node.js Client Example

class EnkryptGatewayAPI {
    constructor(baseUrl = 'http://localhost:8001', apiKey) {
        this.baseUrl = baseUrl;
        this.headers = {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
        };
    }

    async listConfigs() {
        const response = await fetch(`${this.baseUrl}/api/v1/configs`, {
            headers: this.headers
        });
        return response.json();
    }

    async createConfig(configName) {
        const response = await fetch(`${this.baseUrl}/api/v1/configs`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify({ config_name: configName })
        });
        return response.json();
    }
}

// Usage
const api = new EnkryptGatewayAPI('http://localhost:8001', 'your_api_key');
api.listConfigs().then(configs => console.log(configs));

This REST API provides complete programmatic access to all CLI functionality, making it easy to integrate the Enkrypt Secure MCP Gateway into your applications and workflows.