API Integration Security Standards

1. Introduction

1.1 Purpose & Scope

This document defines the mandatory architectural and security standards for any third-party integration connecting to an xAssets instance. These standards ensure system high-availability, data integrity, protection against resource exhaustion, and compliance with industry security frameworks including the OWASP API Security Top 10 (2023).

All integrations—whether custom-built, developed by partners, or utilising AI agents—MUST comply with these requirements before deployment to production environments.

1.2 Intended Audience

• Third-party developers building integrations with xAssets
• Customer IT teams implementing API-based workflows
• Security auditors reviewing integration compliance
• AI/ML engineers developing agent-based automation

1.3 Requirement Terminology

This document uses RFC 2119 terminology:

• MUST / REQUIRED — Absolute requirement; non-compliance blocks production deployment
• SHOULD / RECOMMENDED — Best practice; exceptions require documented justification
• MAY / OPTIONAL — Discretionary; implementation encouraged but not mandated

2. Authentication & Authorization

2.1 Credential Types

xAssets supports the following authentication mechanisms:

2.2 Token Lifecycle Management

• Bearer tokens and API keys MUST be stored in encrypted environment variables, secrets managers, or hardware security modules (HSM).
• Hard-coding credentials in source files is strictly prohibited.
• Tokens SHOULD have a maximum lifetime of 24 hours for interactive sessions, 90 days for service accounts.
• Integrations MUST implement token refresh logic before expiry to avoid service interruption.
• Compromised credentials MUST be reported immediately and revoked within 1 hour of detection.

2.3 Object-Level Authorization (OWASP API1)

• Every API request accessing a specific object (e.g., AssetID=1001) MUST validate that the authenticated user/service has permission to access that specific object.
• Integrations MUST NOT assume that authentication alone grants access to any object ID.
• Sequential ID enumeration attacks MUST be prevented—integrations SHOULD NOT iterate through object IDs to discover records.
• Access control checks MUST occur on every request, not just at session establishment.

2.4 Function-Level Authorization (OWASP API5)

• API credentials MUST be scoped to specific permitted operations (read, write, delete).
• Integrations MUST document all endpoints they require access to; requests to undocumented endpoints will be rejected.
• Administrative functions MUST require elevated credentials separate from standard API access.
• The principle of least privilege MUST be applied—request only the minimum permissions necessary.

2.5 Multi-Factor Authentication

• Interactive user sessions accessing the API through developer portals SHOULD require MFA.
• Service accounts MAY be exempted from MFA but MUST use IP whitelisting or certificate-based authentication as compensating controls.

3. Transport & Data Security

3.1 TLS Requirements

• All API traffic MUST be encrypted using TLS 1.2 or higher.
• TLS 1.0 and 1.1 are not supported and connections will be rejected.
• Self-signed certificates in production environments are not permitted.
• Certificate pinning is RECOMMENDED for high-security integrations.

3.2 Cipher Suite Requirements

Integrations MUST support modern cipher suites. The following are prohibited:

• RC4, DES, 3DES cipher suites
• MD5 or SHA-1 for certificate signatures
• Key exchange without forward secrecy

3.3 Payload Security

• Sensitive data within payloads (e.g., serial numbers, financial values) SHOULD be encrypted at the field level where regulatory requirements apply.
• API responses MUST NOT include credentials, tokens, or internal system identifiers in error messages.

3.4 PII Handling & Masking

• Personally Identifiable Information (PII) MUST be identified and classified before transmission.
• PII SHOULD be masked or tokenised in logs, debug output, and non-production environments.
• Full PII MUST NOT be written to unencrypted storage, temporary files, or browser local storage.

4. API Consumption Standards

4.1 Rate Limiting & Throttling

• xAssets enforces rate limits per API credential. Current limits are communicated via response headers:
  • X-RateLimit-Limit: Maximum requests permitted per window
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when the window resets
• Integrations MUST monitor these headers and throttle requests proactively.
• When receiving HTTP 429 Too Many Requests, integrations MUST implement exponential backoff:
  • Initial retry: 1 second
  • Subsequent retries: Double the previous wait (2s, 4s, 8s...)
  • Maximum backoff: 60 seconds
  • Maximum retry attempts: 5

4.2 Pagination Requirements (OWASP API4)

• All GET requests returning collections MUST implement pagination.
• Default page size: 100 records. Integrations SHOULD NOT override this without justification.
• Maximum page size: 1,000 records. Requests exceeding this will be rejected.
• Integrations MUST handle pagination tokens/cursors to retrieve complete datasets across multiple requests.

4.3 Delta Query Usage

• Integrations SHOULD utilise ModifiedDate filters to fetch only changed records rather than full-table refreshes.
• Initial synchronisation MAY retrieve full datasets; subsequent syncs MUST be incremental.
• Delta queries reduce load on both client and server, improving performance for all tenants.

4.4 Idempotency Requirements

• POST and PUT operations SHOULD include an Idempotency-Key header to prevent duplicate record creation from retry loops.
• The server will cache responses for idempotent requests for 24 hours.
• Integrations MUST generate unique idempotency keys per logical operation (UUIDs recommended).

4.5 Request Timeout Handling

• Client-side timeouts SHOULD be set to 30 seconds for standard operations, 120 seconds for bulk operations.
• Integrations MUST NOT retry timed-out write operations without idempotency keys.
• Long-running operations SHOULD use asynchronous patterns with status polling.

4.6 Error Handling & Information Disclosure (OWASP API8)

• xAssets returns standardised error responses. Integrations MUST handle all HTTP status codes appropriately:

  Code	Meaning	Client Action
  400	Bad Request	Fix request syntax/validation
  401	Unauthorised	Refresh credentials
  403	Forbidden	Check permissions; do not retry
  404	Not Found	Verify resource exists
  429	Rate Limited	Backoff and retry
  500	Server Error	Retry with backoff; report if persistent
  503	Service Unavailable	Retry after Retry-After header value

• Error responses intentionally omit internal details (stack traces, SQL errors, internal paths) to prevent information leakage.
• Integrations MUST NOT expose raw API error messages to end users without sanitisation.

5. Input Validation & Output Controls

5.1 Request Validation Requirements

• All incoming data MUST be validated against a strict schema before processing.
• Content-Type headers MUST match the actual payload format; mismatches will be rejected.
• Request body size MUST NOT exceed 10MB for standard operations, 100MB for bulk imports.
• Field-level validation:
  • String fields: Maximum 4,000 characters unless otherwise documented
  • Numeric fields: Range validation per field definition
  • Date fields: ISO 8601 format required
  • Email fields: RFC 5322 validation

5.2 Injection Prevention

• SQL Injection: xAssets uses parameterised queries internally. Integrations MUST NOT construct dynamic queries by concatenating user input.
• XSS Prevention: Data submitted via API that will be rendered in UI MUST be sanitised. The API will reject payloads containing:
  • <script> tags or event handlers (onclick, onerror, etc.)
  • JavaScript protocol handlers (javascript:)
  • Data URIs with executable content
• SSRF Prevention (OWASP API7): Where integrations accept URLs as input:
  • MUST validate against a whitelist of permitted domains
  • MUST block private IP ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x, 127.x.x.x)
  • MUST NOT allow user-supplied URLs to be fetched server-side without validation

5.3 Field-Level Data Exposure Controls (OWASP API3)

• Integrations SHOULD request only the fields they require using field selection parameters.
• "SELECT *" patterns are discouraged—APIs may return additional fields in future versions, potentially exposing unintended data.
• Sensitive fields (e.g., purchase prices, warranty costs) require explicit permission grants in the API credential scope.

5.4 File Upload Controls

Where integrations upload attachments:

• Permitted file types: PDF, PNG, JPG, JPEG, GIF, DOC, DOCX, XLS, XLSX, CSV, TXT
• Maximum file size: 25MB per file
• Files MUST be scanned for malware before storage
• Executable files (.exe, .bat, .sh, .ps1, etc.) are prohibited
• File names MUST be sanitised to remove path traversal characters

6. Database & Tenant Isolation

6.1 Schema Isolation Requirements

• API credentials are scoped to a specific tenant/database. Cross-tenant queries are architecturally impossible.
• Integrations MUST NOT attempt to "discover" or traverse sibling databases on shared infrastructure.
• Connection strings provided to integrations are valid only for the assigned tenant.

6.2 Cross-Tenant Access Prevention

• Each API request is validated against the tenant context of the credential.
• Attempts to access objects belonging to other tenants will return 403 Forbidden with no additional information.
• Suspicious access patterns (repeated 403s, ID enumeration) will trigger security alerts and potential credential suspension.

6.3 Write-Back Safety Controls

• Any POST, PUT, or DELETE action SHOULD implement a "Dry Run" or "Preview" mode for testing before live execution.
• Include X-DryRun: true header to validate operations without committing changes.
• Bulk operations MUST support transaction rollback on partial failure.
• Delete operations SHOULD use soft-delete patterns where supported, with configurable retention periods.

7. AI Agent-Specific Requirements

7.1 Agent Identity & Authentication

• AI agents MUST authenticate using dedicated service credentials, not shared or user-impersonation tokens.
• Agent credentials MUST be clearly identifiable in audit logs (e.g., prefix AI-AGENT-).
• Each distinct AI agent or workflow SHOULD have its own credential set for granular access control and audit trails.
• Agent-to-agent communication (where multiple AI components interact) MUST use authenticated channels with mutual TLS or signed requests.

7.2 Loop & Recursion Control

• Maximum Step Limit: Agents MUST have a hard-coded maximum iteration cap. Recommended limit: 10 sequential API calls per user prompt. Absolute maximum: 25 calls.
• Time-to-Live (TTL): Every agent request chain MUST have a timeout threshold. Recommended: 120 seconds. Maximum: 300 seconds.
• Cost Controls: Agents MUST implement budget caps to prevent runaway costs from hallucination loops:
  • Per-session API call limit
  • Per-day aggregate limit per credential
  • Alerting at 80% threshold
• Agents MUST NOT spawn recursive sub-agents without explicit depth limits.

7.3 Prompt Injection Prevention

7.3.1 Direct Prompt Injection

• User-provided text MUST be sanitised before being processed by agent logic.
• Inputs MUST be stripped of potential "jailbreak" commands including:
  • Instructions to "ignore previous instructions"
  • Attempts to redefine agent role or permissions
  • Requests to output system prompts or configuration
  • Commands disguised as data (e.g., JSON with embedded instructions)
• Agents SHOULD use a secondary classifier model to evaluate inputs for malicious intent before processing.

7.3.2 Indirect Prompt Injection

• Data retrieved from the xAssets database or external sources MUST be treated as untrusted input.
• Malicious instructions may be embedded in:
  • Asset descriptions or notes fields
  • Imported CSV/Excel data
  • Email content or ticket descriptions
  • Document attachments processed by the agent
• Agents MUST NOT execute instructions found in retrieved data without explicit validation.
• System prompts MUST clearly delineate trusted instructions from user/data content.

7.4 System Prompt Hardening

• Integration code MUST include "System Instructions" that explicitly forbid:
  • Unauthorised data deletions
  • Schema modifications
  • Cross-database queries
  • Credential or token disclosure
  • Execution of arbitrary code
• System prompts SHOULD be versioned and immutable at runtime.
• Changes to system prompts MUST go through the same change control process as code deployments.

7.5 Output Filtering & Validation

• Agent outputs MUST be validated before being returned to users or written to the database.
• Outputs MUST be filtered for:
  • Accidental PII disclosure
  • Internal system information (connection strings, paths, credentials)
  • Hallucinated data that contradicts source records
  • Content that violates organisational policies
• Consider using a secondary "safety model" to review agent outputs before delivery.
• HTML/JavaScript in agent outputs MUST be escaped before rendering in browsers to prevent XSS.

7.6 Session & Context Isolation

• Stateless Context Management: Agents MUST ensure that "conversation memory" is isolated per user session.
• Under no circumstances should User A's data be accessible via User B's session context.
• Context windows SHOULD be limited to the minimum necessary conversation history.
• Session data MUST be cleared upon session termination or timeout.
• Agents MUST NOT share learned behaviours or patterns across tenant boundaries.

7.7 Data Privacy & PII Protection

• Zero-Persistence of PII: Sensitive data retrieved via API MUST NOT be:
  • Written to unencrypted logs
  • Stored in local text files or caches
  • Transmitted to AI model training pipelines
  • Included in error reports or telemetry
• PII SHOULD be masked or tokenised before being passed to AI models, with restoration only on authorised output.
• Conversation logs containing user queries MUST be encrypted at rest and have defined retention limits.

7.8 Human-in-the-Loop Requirements

Certain operations MUST require human approval before execution:

7.9 Model Version Control

• Integrations MUST document which AI model version is in use (e.g., "GPT-4-turbo-2024-04-09", "Claude-3-Sonnet").
• Model upgrades MUST NOT occur automatically in production; changes require testing and approval.
• Behaviour changes between model versions MUST be evaluated for security implications.
• Fallback behaviour MUST be defined for when AI services are unavailable (graceful degradation, not silent failure).

7.10 Sandboxed Execution

• Where agents generate or execute code, this MUST occur in sandboxed environments.
• Sandboxes MUST:
  • Have no network access except to whitelisted endpoints
  • Run with minimal filesystem permissions
  • Have resource limits (CPU, memory, execution time)
  • Be destroyed after each execution
• Model-generated code MUST NOT be trusted—treat as untrusted input.

8. Logging, Monitoring & Observability

8.1 Required Audit Events

The following events MUST be logged with timestamp, user/credential ID, source IP, and correlation ID:

• Authentication attempts (success and failure)
• Authorisation failures (403 responses)
• All create, update, and delete operations
• Rate limit violations
• Input validation failures
• API errors (4xx and 5xx responses)
• For AI agents: Full reasoning chain and tool invocations

8.2 Log Content Standards

Logs MUST include:

• Timestamp (ISO 8601 format, UTC)
• Correlation/Request ID (unique per request chain)
• Credential identifier (not the credential itself)
• Source IP address
• HTTP method and endpoint
• Response status code
• Response time

Logs MUST NOT include:

• Raw credentials, tokens, or API keys
• Full request/response bodies containing PII
• Password or secret values
• Credit card or payment information

8.3 Retention Requirements

• Minimum retention: 90 days for operational logs
• Security audit logs: 1 year minimum (or as required by applicable regulations)
• Logs MUST be stored in tamper-evident format (append-only, signed, or blockchain-anchored)
• Log deletion MUST follow secure disposal procedures

8.4 AI Reasoning Chain Visibility

For AI agent integrations, additional observability is REQUIRED:

• Each agent "thought" or reasoning step MUST be logged
• Tool/API invocations MUST be traceable to the triggering reasoning step
• Token usage and cost per request SHOULD be tracked
• Logs MUST support replay and debugging of agent decisions
• Confidence scores (where available) SHOULD be recorded

8.5 Alerting Requirements

Integrations SHOULD implement alerting for:

• Repeated authentication failures (potential brute force)
• Rate limit violations exceeding threshold
• Unusual access patterns (time, volume, geography)
• AI agent loop detection (excessive API calls in single session)
• Error rate spikes

9. API Lifecycle Management

9.1 Version Identification

• All API requests MUST include a version identifier via the Accept header or URL path.
• Example: Accept: application/vnd.xassets.v2+json or /api/v2/assets
• Requests without version specification will receive the current stable version (not latest/beta).

9.2 Deprecation Policy

• API versions will be supported for a minimum of 24 months after initial release.
• Deprecation notices will be communicated at least 6 months before retirement.
• Deprecated APIs will return warning headers: Deprecation: true and Sunset: <date>
• Integrations MUST monitor for deprecation headers and plan migration accordingly.

9.3 Breaking Change Communication

• Breaking changes (field removals, type changes, behaviour modifications) will only occur in major version increments.
• Change logs will be published with each release detailing all modifications.
• Integrations will be notified via registered contact email at least 90 days before breaking changes take effect.

9.4 API Inventory Management (OWASP API9)

• Integrations MUST maintain documentation of all API endpoints in use.
• Unused or legacy endpoints MUST be decommissioned promptly.
• "Shadow" integrations (undocumented API usage) are prohibited.
• Annual review of API usage and permissions is RECOMMENDED.

10. Testing & Quality Assurance

10.1 Sandbox Environment Requirements

• All integration development and testing MUST occur in sandbox/non-production environments.
• Sandbox credentials MUST NOT be used in production; production credentials MUST NOT be used in testing.
• Test data SHOULD be synthetic; production data MUST NOT be used in non-production environments without anonymisation.

10.2 Security Testing Requirements

Before production deployment, integrations MUST undergo:

• Static Application Security Testing (SAST): Code analysis for vulnerabilities
• Dependency Scanning: Check for known vulnerabilities in libraries
• Credential Scanning: Verify no secrets in source control
• For AI Agents: Prompt injection testing with adversarial inputs

10.3 Load Testing Policies

• Load testing MUST be coordinated with xAssets support to avoid impacting other tenants.
• Load tests MUST use sandbox environments only.
• Sustained load exceeding 100 requests/second requires prior approval.

10.4 Penetration Testing

• Annual penetration testing of integrations is RECOMMENDED for high-security deployments.
• Findings rated Critical or High MUST be remediated before production deployment.
• Penetration testing of xAssets infrastructure requires explicit written authorisation.

11. Compliance & Data Protection

11.1 Applicable Regulations

Integrations processing data subject to regulation MUST comply with applicable requirements including:

• GDPR (EU/UK): Personal data processing, right to erasure, data portability
• CCPA/CPRA (California): Consumer data rights
• SOC 2 Type II: Security, availability, processing integrity controls
• ISO 27001: Information security management
• HIPAA (where applicable): Protected health information
• PCI DSS (where applicable): Payment card data

11.2 Data Residency Requirements

• Data retrieved via API MUST be processed and stored in accordance with tenant data residency requirements.
• Cross-border data transfers MUST comply with applicable data protection laws.
• Integrations MUST document where data is processed and stored.

11.3 Data Retention & Deletion

• Integrations MUST NOT retain xAssets data longer than necessary for the stated purpose.
• Data deletion requests from xAssets (e.g., GDPR right to erasure) MUST be honoured within 30 days.
• Cached or replicated data MUST be included in deletion scope.

11.4 Third-Party Sub-Processors

• If integration code uses third-party services that process xAssets data, these MUST be disclosed.
• Sub-processors MUST maintain equivalent security standards.
• AI model providers (OpenAI, Anthropic, etc.) MUST NOT retain customer data for training unless explicitly authorised.

12. Incident Response

12.1 Security Contact Information

Security issues related to xAssets integrations should be reported to:

• Email: security@xassets.net
• Response SLA: Acknowledgement within 24 hours; triage within 72 hours

12.2 Vulnerability Reporting

• xAssets operates a responsible disclosure programme.
• Discovered vulnerabilities should be reported privately before public disclosure.
• Reporters will be credited (if desired) once the vulnerability is resolved.

12.3 Incident Communication

• In the event of a security incident affecting integrations, xAssets will:
  • Notify affected parties within 72 hours of confirmation
  • Provide incident details appropriate to the severity
  • Issue guidance on mitigation actions required by integration partners
  • Publish post-incident review (where appropriate)

12.4 Integration Partner Obligations

• Suspected security incidents involving xAssets data MUST be reported within 24 hours of detection.
• Integration partners MUST cooperate with incident investigation.
• Compromised credentials MUST be revoked immediately and reported.

13. Pre-Production Audit Checklist

Before moving to production, a Code Review Gate will be conducted. The audit will verify compliance with the following requirements:

Authentication & Authorization

Transport & Data Security

API Consumption

Input Validation & Security

Tenant Isolation

AI Agent Requirements (If Applicable)

Logging & Observability

Compliance