Skip to content

Advanced Security API

This document provides detailed information about the API endpoints related to the advanced security features in the UBU Finance backend, including the Adaptive Zero-Trust Engine and the Consent & Privacy Framework.

Zero-Trust API Endpoints

The Zero-Trust Engine provides several API endpoints for managing risk-based authentication, device posture checks, and geo-fencing.

Risk Assessment

Get Current Risk Assessment

GET /api/security/risk-assessment

Retrieves the current risk assessment for the authenticated user.

Response

{
  "risk_level": "medium",
  "risk_factors": [
    "New device detected",
    "Unusual login time"
  ],
  "requires_mfa": true,
  "mfa_type": "otp",
  "timestamp": "2025-05-26T16:45:32Z"
}

Submit MFA Verification

POST /api/security/mfa/verify

Submits an MFA token for verification.

Request Body

{
  "mfa_type": "otp",
  "mfa_token": "123456"
}

Response

{
  "status": "success",
  "message": "MFA verification successful",
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Device Management

Register Device

POST /api/security/devices

Registers a new device for the authenticated user.

Request Body

{
  "device_name": "My Work Laptop",
  "device_type": "desktop",
  "trusted": true
}

Response

{
  "status": "success",
  "device_id": "d8f7a3b2-1c5e-4f9a-8d6b-7e5a4c3b2d1e",
  "message": "Device registered successfully"
}

List Registered Devices

GET /api/security/devices

Lists all registered devices for the authenticated user.

Response

{
  "devices": [
    {
      "device_id": "d8f7a3b2-1c5e-4f9a-8d6b-7e5a4c3b2d1e",
      "device_name": "My Work Laptop",
      "device_type": "desktop",
      "last_seen": "2025-05-26T15:30:22Z",
      "last_ip": "192.168.1.100",
      "trusted": true
    },
    {
      "device_id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
      "device_name": "My Phone",
      "device_type": "mobile",
      "last_seen": "2025-05-26T14:15:10Z",
      "last_ip": "10.0.0.15",
      "trusted": true
    }
  ]
}

Trust/Untrust Device

PUT /api/security/devices/{device_id}/trust

Marks a device as trusted or untrusted.

Request Body

{
  "trusted": true
}

Response

{
  "status": "success",
  "message": "Device trust status updated"
}

Geo-Fencing

Get Allowed Regions

GET /api/security/geo-fencing/regions

Gets the list of allowed geographic regions for the authenticated user.

Response

{
  "allowed_regions": [
    {
      "name": "Headquarters",
      "countries": ["US", "CA", "GB"],
      "description": "Access to all resources"
    },
    {
      "name": "Europe",
      "countries": ["DE", "FR", "ES", "IT", "GB"],
      "description": "Access to European resources"
    }
  ]
}

The Consent Framework provides API endpoints for managing user consent preferences.

GET /api/consent/scopes

Lists all available consent scopes.

Response

{
  "scopes": [
    {
      "scope_id": "essential",
      "name": "Essential Services",
      "description": "Data required for core functionality of UBU Finance services",
      "category": "essential",
      "required": true,
      "data_usage": ["authentication", "transactions", "security"],
      "third_parties": []
    },
    {
      "scope_id": "analytics",
      "name": "Analytics & Improvements",
      "description": "Data used to improve our services and user experience",
      "category": "data_collection",
      "required": false,
      "data_usage": ["analytics", "product_improvement"],
      "third_parties": ["analytics_provider"]
    }
  ]
}

GET /api/consent

Gets the current consent status for the authenticated user.

Response

{
  "consents": {
    "essential": true,
    "analytics": true,
    "marketing": false,
    "third_party_sharing": false,
    "location": true,
    "biometrics": false,
    "sms": true
  },
  "last_updated": "2025-05-26T10:15:30Z"
}

POST /api/consent

Grants consent for specified scopes.

Request Body

{
  "scopes": ["analytics", "location", "sms"]
}

Response

{
  "status": "success",
  "message": "Consent granted",
  "token_id": "c7d8e9f0-a1b2-3c4d-5e6f-7g8h9i0j1k2l",
  "scopes": ["analytics", "location", "sms"]
}

DELETE /api/consent/{scope_id}

Revokes consent for a specific scope.

Response

{
  "status": "success",
  "message": "Consent revoked for scope: analytics"
}

GET /api/consent/audit

Gets the consent audit trail for the authenticated user.

Response

{
  "audit_trail": [
    {
      "record_id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
      "action": "grant",
      "scopes": ["analytics", "location", "sms"],
      "timestamp": "2025-05-26T10:15:30Z",
      "ip_address": "192.168.1.100"
    },
    {
      "record_id": "b2c3d4e5-f6g7-8901-b2c3-d4e5f6g7h8i9",
      "action": "revoke",
      "scopes": ["marketing"],
      "timestamp": "2025-05-26T11:30:45Z",
      "ip_address": "192.168.1.100"
    }
  ]
}

Integration Examples

Requiring MFA for High-Value Transactions

This example shows how to integrate the Zero-Trust Engine with a transaction endpoint to require MFA for high-value transactions.

from fastapi import Depends, HTTPException
from app.security.zero_trust import require_mfa

@app.post("/api/transactions")
async def create_transaction(
    transaction: TransactionCreate,
    risk_assessment = Depends(lambda req: require_mfa(req, req.state.user_id, transaction.amount))
):
    # Transaction will only proceed if MFA is verified when required
    # Process transaction
    return {"status": "success", "transaction_id": "..."}

This example shows how to check for user consent before processing analytics data.

from fastapi import Depends
from app.security.consent_framework import require_consent

@app.post("/api/analytics/user-behavior")
async def submit_analytics(
    analytics_data: AnalyticsData,
    consent_check = Depends(lambda req: require_consent(req, req.state.user_id, "analytics"))
):
    # This endpoint will only proceed if the user has granted analytics consent
    # Process analytics data
    return {"status": "success"}

Error Responses

MFA Required Error

{
  "detail": {
    "message": "MFA required",
    "mfa_type": "otp",
    "risk_level": "high",
    "risk_factors": ["High-value transaction ($5000.00)", "New device detected"]
  }
}

{
  "detail": {
    "message": "Consent required for Analytics & Improvements",
    "scope_id": "analytics",
    "scope_name": "Analytics & Improvements",
    "scope_description": "Data used to improve our services and user experience"
  }
}

Geo-Fencing Error

{
  "detail": {
    "message": "Access denied from your location to headquarters resources"
  }
}

Security Considerations

When using these API endpoints, keep the following security considerations in mind:

  1. Always Use HTTPS: All API requests should be made over HTTPS to ensure data confidentiality.
  2. Validate Tokens: Always validate authentication tokens on the server side.
  3. Implement Rate Limiting: Implement rate limiting to prevent brute force attacks on MFA verification endpoints.
  4. Secure Storage: Store consent records securely and maintain an immutable audit trail.
  5. Privacy by Design: Follow privacy by design principles and only collect necessary data.
  6. Regular Audits: Regularly audit consent records and risk assessments to ensure compliance with regulations.