Security Model

This page describes how TengineAI handles credentials, session boundaries, and secret management. It is intended for security reviewers, infrastructure buyers, and developers who need to understand the trust model before integrating.

Outbound Authentication for Your APIs

When TengineAI calls your API on behalf of a tool execution, it can authenticate the request so your API can verify the call came from TengineAI and not an arbitrary caller.

Three strategies are available per tool:

Strategy	`auth_strategy`	How TengineAI authenticates
None	`none`	No auth headers added
Static Bearer	`static_bearer`	`Authorization: Bearer <secret>`
HMAC Signature	`hmac_signature`	`X-Tengine-Signature: tng1=<hex>` over canonical string

HMAC signature is recommended for production. It provides origin verification, body integrity, and replay protection via timestamp.

See Outbound Authentication for the full canonical string specification and Python verification code.

Credential Storage

HMAC Secrets and Bearer Tokens (`encrypted_auth_secret`)

When you configure outbound auth for a custom tool, the encrypted_auth_secret is:

Stored encrypted at rest — encrypted before being written to the database
Decrypted in-memory at execution time — the plaintext is held in memory only for the duration of the tool call, then discarded
Never returned in any API response — you cannot retrieve the plaintext after creation; if lost, update with a new value

TengineAI Project API Keys

Project API keys (tengine_...) are hashed before storage using a one-way hash. TengineAI cannot recover the plaintext of an existing key. If a key is lost, it must be rotated by creating a new integration.

Session Boundary Enforcement

Project Isolation

Each project has its own API keys, tool list, and credential configuration. A token authenticated against Project A cannot access Project B's tools or secrets under any circumstances. Isolation is enforced at the data layer.

Member Session Tokens

Member session tokens (tng_mst_...) are short-lived JWTs (default 15-minute TTL) signed by TengineAI. They encode project_id, integration_id, and member_external_id. A token for Project A, Member Alice cannot be used to execute tools under Project B or as Member Bob — the claims are verified on every request.

Tool Gating

The model only receives tool definitions for tools explicitly enabled in the project. Disabled tools are invisible at the protocol level — they are never returned in list_tools and cannot be called even if the caller knows the tool name.

Assertion Key Security (User-Scoped Sessions)

User-scoped sessions use asymmetric cryptography:

Your private key signs the member_assertion JWT — it lives on your backend only and is never sent to TengineAI
Your public key is registered with TengineAI (associated with a kid)
TengineAI verifies the assertion signature against the registered public key before issuing a session token

This means:

TengineAI never sees your private key
A breach of TengineAI's public key registry cannot be used to forge assertions — only your private key can sign valid assertions
Key rotation is zero-downtime: register the new key → migrate signing → deactivate the old key

HMAC Signing Coverage

For tools using hmac_signature, the signature covers:

Timestamp — prevents replay attacks (reject requests older than your tolerance window, recommended ≤ 5 minutes)
HTTP method and full URL including host — prevents cross-endpoint relay attacks
SHA256 of the request body — prevents body tampering in transit
Project ID and member ID — scopes the signature to a specific execution context

See the Outbound Authentication reference for the exact canonical string format.

Identity Header Injection

TengineAI injects the following headers on every outbound tool call. Your API can use these to identify the caller and enforce access control without a separate token exchange:

Header	Always Present	Value
`X-Tengine-Project-Id`	✅	Your TengineAI project ID
`X-Tengine-Integration-Id`	✅	The integration ID
`X-Tengine-Request-Id`	✅	UUID per request — use for deduplication/logging
`X-Tengine-Timestamp`	✅	Unix seconds — use for replay protection
`X-Tengine-Member-Id`	When `inject_member_identity.id = true`	Member's external ID

Validate X-Tengine-Project-Id in your API to confirm the request originated from your expected project.

Rotation

Credential	How to Rotate
Project API key	Delete and recreate the integration. Old key is invalidated immediately.
Custom tool HMAC secret	`PATCH /api/v1/custom-tools/<id>` with new `encrypted_auth_secret`.
Custom tool bearer token	Same — `PATCH` with new `encrypted_auth_secret`.
Assertion public key	Register new key with new `kid`, update signing code, then deactivate old key via `DELETE /api/v1/assertion-keys/<id>`.

What TengineAI Cannot Do

Forge member assertions — TengineAI only verifies assertions; it cannot sign them as your backend
Access resources outside a project's scope — project isolation is enforced at the data layer, not just the API layer
Return encrypted secrets in plaintext — once stored, encrypted_auth_secret values cannot be retrieved; only updated

Next Steps

Outbound Authentication — HMAC signing spec, verification code, and common mistakes
Error Reference — Error codes and how to resolve them
Production Checklist — Pre-launch security and operational checklist