API Integration Security Standards

1. Introduction

1.1 Purpose and Scope

This document covers the mandatory architectural and security standards for third-party integrations connecting to an xAssets instance. These standards ensure server resource protection, high-availability, data integrity, data security, 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 or required - Absolute requirement. Non-compliance blocks production deployment
• Should or recommended - Best practice. Exceptions require documented justification
• May or optional - Discretionary. Implementation encouraged but not mandatory

2. Authentication and Authorization

2.1 Credential Types

xAssets supports the following authentication mechanisms:

2.2 Token Lifecycle Management

• API keys must be stored in encrypted files, secrets managers, or hardware security modules (HSM).
• In memory storage should use encrypted variables such as SecureString objects
• Hard-coding credentials in source files is prohibited.
• Tokens should have a maximum lifetime of 24 hours for interactive sessions, 90 days for service accounts (a maximum of 90 days unless shorter lifetimes are enforced by policy).
• 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.
• Error messages must remove file paths and secure user information

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 and 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 with a minimum of 128 bit encryption. 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, personal data, or internal system identifiers in error messages.

3.4 PII Handling and 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 and 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
• Detection Of
  • Credential sharing
  • Abnormal Request Patterns
  • Automation behaving outside of its declared use case

xAssets reserves the right to suspend credentials without notice for abuse where clear evidence of misuse exists.

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 and 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 and 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, TSV
• Maximum file size: 25MB per file
• Files must be scanned for malware before storage
• Executable and script files (.exe, .bat, .sh, .ps1, etc.) are prohibited
• File names must be sanitised to remove path traversal characters (..\, ../, etc.)

6. Database and 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.
• Integrations must NOT attempt to access database system tables.
• 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 and 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 and 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 and 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 and 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 and 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.
• AI agents must NOT transmit xAssets data to non-declared external endpoints

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 and 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: Decision trace including inputs, tool invocations, parameters (redacted), outputs, and final actions. Raw model chain-of-thought must not be persisted

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 and 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 and 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.
• Integrations must classify data they consume according to xAssets data classification
  • Public
  • Internal
  • Confidential
  • Restricted

11.3 Data Retention and 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:

• xAssets Support
• 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 will be conducted by xAssets. The audit includes the use of LAN based AI tools owned by xAssets (your code is not exposed to any third party). The audit will review your source code and verify compliance with the following requirements:

Authentication and Authorization

Transport and Data Security

API Consumption

Input Validation and Security

Tenant Isolation

AI Agent Requirements (If Applicable)

Logging and Observability

Compliance