Skip to main content

​
Overview

User endpoints allow you to create and manage users, view their project associations, and manage their API keys. Users are the entities that authenticate to the gateway and are associated with specific projects.

​
List All Users

Retrieve a list of all users in the system. 
curl -X GET "http://localhost:8001/api/v1/users" \
  -H "Authorization: Bearer ${ADMIN_KEY}"
Response: 200 OK 
{
  "message": "Users retrieved successfully",
  "data": [
    {
      "user_id": "440e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "projects_count": 2,
      "api_keys_count": 3,
      "created_at": "2024-01-01T12:00:00.000000"
    },
    {
      "user_id": "330e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "projects_count": 1,
      "api_keys_count": 1,
      "created_at": "2024-01-01T12:00:00.000000"
    }
  ],
  "timestamp": "2024-01-01T12:00:00.000000"
}
​
data
array

​
Create User

Create a new user with an email address. 
curl -X POST "http://localhost:8001/api/v1/users" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
​
email
string
required
Valid email address for the new user (must be unique)
Response: 200 OK 
{
  "message": "User created successfully",
  "data": {
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]"
  },
  "timestamp": "2024-01-01T12:00:00.000000"
}
Error Response: 400 Bad Request (if email already exists) 
{
  "error": "User creation failed",
  "detail": "User with email [email protected] already exists",
  "timestamp": "2024-01-01T12:00:00.000000"
}

​
Get User

Retrieve details of a specific user. 
curl -X GET "http://localhost:8001/api/v1/users/{user_identifier}" \
  -H "Authorization: Bearer ${ADMIN_KEY}"
​
user_identifier
string
required
User ID or email address
Response: 200 OK 
{
  "message": "User retrieved successfully",
  "data": {
    "user_id": "440e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "projects": [
      {
        "project_id": "660e8400-e29b-41d4-a716-446655440000",
        "project_name": "development-project"
      },
      {
        "project_id": "770e8400-e29b-41d4-a716-446655440000",
        "project_name": "staging-project"
      }
    ],
    "api_keys_count": 3,
    "created_at": "2024-01-01T12:00:00.000000"
  },
  "timestamp": "2024-01-01T12:00:00.000000"
}

​
Update User

Update a user’s email address. 
curl -X PUT "http://localhost:8001/api/v1/users/{user_identifier}" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"new_email": "[email protected]"}'
​
user_identifier
string
required
User ID or current email address
​
new_email
string
required
New email address for the user (must be unique)
Response: 200 OK 
{
  "message": "User updated successfully",
  "timestamp": "2024-01-01T12:00:00.000000"
}

​
Delete User

Delete a user and optionally force deletion even if they have active projects or API keys.
Deleting a user will invalidate all their API keys and remove them from all projects.
curl -X DELETE "http://localhost:8001/api/v1/users/{user_identifier}" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"force": false}'
​
user_identifier
string
required
User ID or email address
​
force
boolean
Force deletion even if user has active projects or API keys (default: false)
Response: 200 OK 
{
  "message": "User deleted successfully",
  "timestamp": "2024-01-01T12:00:00.000000"
}
Error Response: 400 Bad Request (if force=false and user has dependencies) 
{
  "error": "User deletion failed",
  "detail": "User has active projects or API keys. Use force=true to delete anyway.",
  "timestamp": "2024-01-01T12:00:00.000000"
}

​
List User Projects

Get all projects a user belongs to. 
curl -X GET "http://localhost:8001/api/v1/users/{user_identifier}/projects" \
  -H "Authorization: Bearer ${ADMIN_KEY}"
​
user_identifier
string
required
User ID or email address
Response: 200 OK 
{
  "message": "User projects retrieved successfully",
  "data": [
    {
      "project_id": "660e8400-e29b-41d4-a716-446655440000",
      "project_name": "development-project",
      "mcp_config_name": "dev-config",
      "created_at": "2024-01-01T12:00:00.000000"
    },
    {
      "project_id": "770e8400-e29b-41d4-a716-446655440000",
      "project_name": "production-project",
      "mcp_config_name": "prod-config",
      "created_at": "2024-01-01T12:00:00.000000"
    }
  ],
  "timestamp": "2024-01-01T12:00:00.000000"
}

​
List User API Keys

Get all API keys for a user, optionally filtered by project. 
# All API keys for user
curl -X GET "http://localhost:8001/api/v1/users/{user_identifier}/api-keys" \
  -H "Authorization: Bearer ${ADMIN_KEY}"

# API keys for specific project
curl -X GET "http://localhost:8001/api/v1/users/{user_identifier}/api-keys?project_identifier=project-name" \
  -H "Authorization: Bearer ${ADMIN_KEY}"
​
user_identifier
string
required
User ID or email address
​
project_identifier
string
Optional project ID or name to filter API keys
Response: 200 OK 
{
  "message": "User API keys retrieved successfully",
  "data": [
    {
      "api_key": "gw_abc123...xyz789",
      "project_id": "660e8400-e29b-41d4-a716-446655440000",
      "project_name": "development-project",
      "created_at": "2024-01-01T12:00:00.000000",
      "status": "active"
    },
    {
      "api_key": "gw_def456...uvw012",
      "project_id": "770e8400-e29b-41d4-a716-446655440000",
      "project_name": "production-project",
      "created_at": "2024-01-02T12:00:00.000000",
      "status": "active"
    }
  ],
  "timestamp": "2024-01-01T12:00:00.000000"
}

​
Generate User API Key

Generate a new API key for a user within a specific project. 
curl -X POST "http://localhost:8001/api/v1/users/{user_identifier}/api-keys" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"project_name": "development-project"}'
​
user_identifier
string
required
User ID or email address
​
project_name
string
Project name (either project_name or project_id required)
​
project_id
string
Project ID (either project_name or project_id required)
Response: 200 OK 
{
  "message": "API key generated successfully",
  "data": {
    "api_key": "gw_abc123xyz789def456uvw012pqr345stu678"
  },
  "timestamp": "2024-01-01T12:00:00.000000"
}
Store the API key securely. It cannot be retrieved again after this response.
Error Response: 400 Bad Request (if user is not in project) 
{
  "error": "API key generation failed",
  "detail": "User is not a member of the specified project",
  "timestamp": "2024-01-01T12:00:00.000000"
}

​
Delete All User API Keys

Delete all API keys for a specific user.
This will invalidate all API keys for the user across all projects.
curl -X DELETE "http://localhost:8001/api/v1/users/{user_identifier}/api-keys" \
  -H "Authorization: Bearer ${ADMIN_KEY}"
​
user_identifier
string
required
User ID or email address
Response: 200 OK 
{
  "message": "All user API keys deleted successfully",
  "timestamp": "2024-01-01T12:00:00.000000"
}

​
Search Users

Search users by email address. 
curl -X POST "http://localhost:8001/api/v1/users/search" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"search_term": "alice"}'
​
search_term
string
required
Search query (matches against email addresses)
Response: 200 OK 
{
  "message": "Search completed successfully",
  "data": [
    {
      "user_id": "440e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "projects_count": 2,
      "created_at": "2024-01-01T12:00:00.000000"
    },
    {
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "projects_count": 1,
      "created_at": "2024-01-01T12:00:00.000000"
    }
  ],
  "timestamp": "2024-01-01T12:00:00.000000"
}

​
Complete User Management Example

Here’s a complete workflow for managing users: 
import requests

class GatewayUserManager:
    def __init__(self, base_url, admin_key):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {admin_key}",
            "Content-Type": "application/json"
        }
    
    def create_user(self, email):
        """Create a new user"""
        response = requests.post(
            f"{self.base_url}/users",
            headers=self.headers,
            json={"email": email}
        )
        return response.json()
    
    def add_to_project(self, user_email, project_name):
        """Add user to a project"""
        response = requests.post(
            f"{self.base_url}/projects/{project_name}/users",
            headers=self.headers,
            json={"email": user_email}
        )
        return response.json()
    
    def generate_api_key(self, user_email, project_name):
        """Generate API key for user in project"""
        response = requests.post(
            f"{self.base_url}/users/{user_email}/api-keys",
            headers=self.headers,
            json={"project_name": project_name}
        )
        return response.json()["data"]["api_key"]
    
    def onboard_user(self, email, project_name):
        """Complete user onboarding workflow"""
        # Create user
        user_result = self.create_user(email)
        print(f"Created user: {user_result}")
        
        # Add to project
        project_result = self.add_to_project(email, project_name)
        print(f"Added to project: {project_result}")
        
        # Generate API key
        api_key = self.generate_api_key(email, project_name)
        print(f"Generated API key: {api_key}")
        
        return {
            "email": email,
            "project": project_name,
            "api_key": api_key
        }

# Usage
manager = GatewayUserManager(
    base_url="http://localhost:8001/api/v1",
    admin_key="your-admin-key"
)

# Onboard a new user
result = manager.onboard_user(
    email="[email protected]",
    project_name="development-project"
)

print(f"User onboarded successfully!")
print(f"API Key: {result['api_key']}")

​
Next Steps

API Key Management

Detailed API key operations

Project Endpoints

Manage user-project associations

Configuration Endpoints

Configure MCP servers

System Endpoints

System operations

Build docs developers (and LLMs) love

Get started for freeTalk to us