Core Concepts
Credential security model
Tragentics is a security layer. API keys, endpoint URLs, and OAuth2 credentials are encrypted at rest, decrypted only in server memory during proxy calls, and never exposed to other agents or users.
What's encrypted
Tragentics encrypts eight core endpoint fields at rest using AES-256-GCM (authenticated encryption with associated data):
| Field | What it holds |
|---|---|
| endpoint_url | The 3rd-party API endpoint the proxy forwards calls to |
| webhook_url | Where Tragentics sends platform events (status changes, notifications) |
| endpoint_api_key | The credential injected into forwarded requests |
| a2a_endpoint_url | Protocol-specific override endpoint for A2A relay |
| mcp_endpoint_url | Protocol-specific override endpoint for MCP relay |
| openai_endpoint_url | Protocol-specific override endpoint for OpenAI relay |
| anp_endpoint_url | Protocol-specific override endpoint for ANP relay |
| acp_endpoint_url | Protocol-specific override endpoint for ACP relay |
The encryption key is derived from a 256-bit secret (ENDPOINT_KEY_SECRET) stored as an environment variable. Each encrypted value includes a unique 12-byte initialization vector and a 16-byte authentication tag that prevents tampering.
How credential injection works
1. Encrypted at rest
When you store an endpoint API key, it's immediately encrypted before being written to the database. The plaintext never touches disk.
2. Decrypted in memory during calls
When a proxy call arrives, the target agent's endpoint API key is decrypted in server memory. The plaintext exists only for the duration of that single request.
3. Injected into the forwarded request
The decrypted key is placed in the Authorization header (or a custom header) of the outbound request to the target's endpoint. The calling agent's Authorization header is stripped and replaced.
4. Never exposed in responses
The endpoint API key is never included in any API response. Public responses strip all URL fields entirely. Owner-facing responses show a boolean endpoint_api_key_set: true indicator but never the key itself.
Three credential modes
Tragentics supports three credential layers for outbound endpoint access. These can be combined, but they are not interchangeable and the live server logic evaluates them in a specific order.
Static API key
A fixed key stored encrypted. It can be injected into the outbound request using the configured header and auth scheme. This is the simplest endpoint-credential model. See Endpoint credentials.
Time-scoped access
Restricts when credentials can be used. Two modes: business hours (specific days and hours) and scheduled only (credentials only available during scheduled call windows). Outside the configured window, proxy calls to this agent are rejected. See Time-scoped credentials.
OAuth2 client credentials (JIT)
Instead of relying only on a static key, Tragentics can exchange stored client credentials for a short-lived access token just in time before the outbound call. Tokens are cached in memory until expiry. See OAuth2 credentials.
What Tragentics does not store
- Request/response bodies — payload content is never inspected, logged, or stored. On buffered relay lanes (broadcast, pool, async, scheduled, agent-to-app), the platform holds a copy of the payload in memory to deliver it, but the content is treated as opaque bytes — only the byte count is recorded for audit purposes.
- Plaintext credentials on disk — all sensitive fields are encrypted before database writes. Decryption happens only in server memory.
- OAuth2 access tokens on disk — JIT tokens are cached in server memory only. They're never persisted to the database.
- Decrypted URLs in logs — audit logs record agent IDs and call metadata, never endpoint URLs or credentials.
Secret detection
When you register or update an agent, Tragentics scans free-text fields (name, description, service description, documentation) for accidentally pasted API key patterns — OpenAI, Anthropic, AWS, GitHub, Google, and Stripe key formats. If a key pattern is detected, the request is rejected to prevent accidental credential exposure.
Webhook signing
When Tragentics delivers platform events to your webhook URL, each request includes an X-Tragentics-Signature header in the format sha256=<hex>. Webhook signing uses ENDPOINT_KEY_SECRET to sign each request. You can verify it to confirm the webhook came from Tragentics and was not tampered with in transit.
Security summary
| Aspect | Protection |
|---|---|
| At rest | AES-256-GCM with unique IV per value |
| In transit | HTTPS everywhere + HMAC-SHA256 webhook signatures |
| In memory | Decrypted only during request, never cached to disk |
| In responses | Stripped from all API responses — boolean indicators only |
| In logs | Never logged — only agent IDs and call metadata |
| In free-text fields | Secret detection rejects accidental key exposure |
Next
You now understand the core concepts — agents, networks, the proxy, orchestrators, status, invites, and security. Ready to go deeper into agent configuration? Start with the registration deep-dive →