Security API 🟡 BETA

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:9000/api/v1/security

Authentication

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

Endpoints

Authentication

MethodEndpointDescription
POST/api/v1/security/auth/loginAuthenticate user
POST/api/v1/security/auth/logoutEnd session
POST/api/v1/security/auth/refreshRefresh access token
POST/api/v1/security/auth/mfa/setupSetup MFA
POST/api/v1/security/auth/mfa/verifyVerify MFA code

API Keys

MethodEndpointDescription
POST/api/v1/security/keys/generateGenerate new API key
GET/api/v1/security/keysList 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

MethodEndpointDescription
GET/api/v1/security/rolesList all roles
POST/api/v1/security/rolesCreate 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/permissionsList all permissions
PUT/api/v1/security/permissionsUpdate permissions

Audit Logs

MethodEndpointDescription
GET/api/v1/security/auditList audit log entries
GET/api/v1/security/audit/{id}Get specific audit entry
POST/api/v1/security/audit/exportExport audit logs
GET/api/v1/security/audit/summaryGet audit summary

Session Management

MethodEndpointDescription
GET/api/v1/security/sessionsList 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

MethodEndpointDescription
GET/api/v1/security/threatsList detected threats
GET/api/v1/security/vulnerabilitiesList vulnerabilities
POST/api/v1/security/scanInitiate 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

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

Security Event Types

Event TypeDescription
login_successSuccessful authentication
login_failedFailed authentication attempt
logoutUser logged out
password_changedPassword was changed
mfa_enabledMFA was enabled
api_key_createdNew API key generated
api_key_revokedAPI key was revoked
role_changedUser role was modified
permission_deniedAccess denied to resource
suspicious_activityPotential security threat detected

Rate Limiting

EndpointLimit
/auth/login5 requests per minute
/auth/mfa/verify3 requests per minute
/keys/generate10 requests per hour
Other endpoints100 requests per minute

Required Permissions

Endpoint CategoryRequired Role
AuthenticationPublic (login) / Authenticated (others)
API Keysadmin or key_manager
Access Controladmin
Audit Logsadmin or auditor
Session Managementadmin or session_manager
Security Monitoringadmin 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