botbook/src/10-rest/security-api.md

Security API

The Security API provides endpoints for security management, access control, and threat monitoring.

Status: Roadmap

This API is on the development roadmap. The endpoints documented below represent the planned interface design.

Base URL

http://localhost:8080/api/v1/security

Authentication

Uses the standard botserver authentication mechanism with elevated security permissions required.

Endpoints

Authentication

Method	Endpoint	Description
POST	/api/v1/security/auth/login	Authenticate user
POST	/api/v1/security/auth/logout	End session
POST	/api/v1/security/auth/refresh	Refresh access token
POST	/api/v1/security/auth/mfa/setup	Setup MFA
POST	/api/v1/security/auth/mfa/verify	Verify MFA code

API Keys

Method	Endpoint	Description
POST	/api/v1/security/keys/generate	Generate new API key
GET	/api/v1/security/keys	List API keys
GET	/api/v1/security/keys/{key_id}	Get key details
PUT	/api/v1/security/keys/{key_id}	Update key permissions
DELETE	/api/v1/security/keys/{key_id}	Revoke API key

Access Control

Method	Endpoint	Description
GET	/api/v1/security/roles	List all roles
POST	/api/v1/security/roles	Create a role
GET	/api/v1/security/roles/{role_id}	Get role details
PUT	/api/v1/security/roles/{role_id}	Update role
DELETE	/api/v1/security/roles/{role_id}	Delete role
GET	/api/v1/security/permissions	List all permissions
PUT	/api/v1/security/permissions	Update permissions

Audit Logs

Method	Endpoint	Description
GET	/api/v1/security/audit	List audit log entries
GET	/api/v1/security/audit/{id}	Get specific audit entry
POST	/api/v1/security/audit/export	Export audit logs
GET	/api/v1/security/audit/summary	Get audit summary

Session Management

Method	Endpoint	Description
GET	/api/v1/security/sessions	List active sessions
GET	/api/v1/security/sessions/{session_id}	Get session details
DELETE	/api/v1/security/sessions/{session_id}	Terminate session
DELETE	/api/v1/security/sessions/user/{user_id}	Terminate all user sessions

Security Monitoring

Method	Endpoint	Description
GET	/api/v1/security/threats	List detected threats
GET	/api/v1/security/vulnerabilities	List vulnerabilities
POST	/api/v1/security/scan	Initiate security scan
GET	/api/v1/security/scan/{scan_id}	Get scan results

Request Examples

Login

credentials = NEW OBJECT
credentials.email = "admin@example.com"
credentials.password = "secure_password"

result = POST "/api/v1/security/auth/login", credentials
token = result.access_token
TALK "Logged in successfully"

Generate API Key

key_config = NEW OBJECT
key_config.name = "Integration Key"
key_config.scopes = ["read:bots", "write:messages"]
key_config.expires_in_days = 90

result = POST "/api/v1/security/keys/generate", key_config
TALK "API Key: " + result.key
TALK "Expires: " + result.expires_at

Create Role

role = NEW OBJECT
role.name = "bot_manager"
role.description = "Can manage bots and configurations"
role.permissions = ["bot:read", "bot:write", "bot:delete", "config:read", "config:write"]

result = POST "/api/v1/security/roles", role
TALK "Role created: " + result.id

List Active Sessions

sessions = GET "/api/v1/security/sessions"
FOR EACH session IN sessions
    TALK session.user_email + " - " + session.ip_address + " (" + session.last_activity + ")"
NEXT

Query Audit Logs

audit = GET "/api/v1/security/audit?action=login&days=7"
FOR EACH entry IN audit
    TALK entry.timestamp + " | " + entry.user + " | " + entry.action + " | " + entry.result
NEXT

Terminate Session

DELETE "/api/v1/security/sessions/session-123"
TALK "Session terminated"

Response Codes

Code	Description
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request
401	Unauthorized (invalid credentials)
403	Forbidden (insufficient permissions)
404	Not Found
429	Too Many Requests (rate limited)
500	Internal Server Error

Security Event Types

Event Type	Description
login_success	Successful authentication
login_failed	Failed authentication attempt
logout	User logged out
password_changed	Password was changed
mfa_enabled	MFA was enabled
api_key_created	New API key generated
api_key_revoked	API key was revoked
role_changed	User role was modified
permission_denied	Access denied to resource
suspicious_activity	Potential security threat detected

Rate Limiting

Endpoint	Limit
/auth/login	5 requests per minute
/auth/mfa/verify	3 requests per minute
/keys/generate	10 requests per hour
Other endpoints	100 requests per minute

Required Permissions

Endpoint Category	Required Role
Authentication	Public (login) / Authenticated (others)
API Keys	admin or key_manager
Access Control	admin
Audit Logs	admin or auditor
Session Management	admin or session_manager
Security Monitoring	admin or security_analyst

Best Practices

1. Use strong passwords - Minimum 12 characters with mixed case, numbers, and symbols
2. Enable MFA - Two-factor authentication for all admin accounts
3. Rotate API keys - Set expiration dates and rotate keys regularly
4. Monitor audit logs - Review security events daily
5. Principle of least privilege - Grant minimum necessary permissions
6. Terminate inactive sessions - Auto-expire sessions after inactivity