Authentication — API Keys

API keys are the simplest way to authenticate with TengineAI. They are project-scoped, long-lived credentials suited for server-to-server workflows, automation pipelines, and any integration where all requests share a single project identity.

API Key vs User-Scoped Sessions

Attribution warning: API key mode attributes all tool calls to the project, not to individual users. If your product serves multiple end users, use User-Scoped Sessions instead. This is the most common architectural mistake when scaling from prototype to production.

Format

TengineAI API keys use the prefix tengine_ followed by a URL-safe random string:

tengine_example_4f8k2m9p7r3x6z1b5c0d2h9q7w

Example only — your actual key will be different and should be kept secret.

Keys are approximately 50–55 characters total. The prefix makes them easy to identify in environment variables, and secret scanners.

Creating an API Key

API keys are created inside an Integration. The key is shown only once at creation time.

1. Go to your TengineAI Dashboard
2. Open your project
3. Navigate to the Integrations tab
4. Click Create Integration
5. Choose Authentication Method: API Key and provide a name (e.g. Backend Server or Local Dev)
6. Click Setup Integration

After setup completes, your new API key will be displayed once. Click Copy and store it immediately — you will not be able to view this key again.

API keys are only visible once. They are hashed on creation and cannot be retrieved later. Keys are never stored in plaintext. If you lose a key, delete the integration and create a new one.

Rotating or Replacing a Key

If a key is lost or compromised:

1. Go to Integrations
2. Delete the affected integration
3. Create a new integration to generate a new key

The old key is invalidated immediately upon deletion.

Revocation propagates instantly — All active sessions using that key are invalidated automatically. New requests with the revoked key are rejected immediately. Revocation applies to subsequent requests; in-flight requests are allowed to complete.

Accepted Header Format

TengineAI expects API keys via the Authorization: Bearer header:

Authorization: Bearer tengine_...

This applies to both MCP integrations and direct REST calls to the management API. The Anthropic SDK sends this header automatically when you provide the key as authorization_token.

Using an API Key with the Anthropic SDK

Pass the API key as authorization_token in the mcp_servers configuration:

import json
import os
import anthropic

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What tools are available?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://app.tengine.ai/mcp/",
            "name": "tengineai",
            "authorization_token": os.environ["TENGINEAI_API_KEY"],
        }
    ],
    betas=["mcp-client-2025-04-04"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)
    elif block.type == "mcp_tool_use":
        print(
            f"[tool_use] server={block.server_name} tool={block.name} id={block.id} "
            f"input={json.dumps(block.input, default=str)}"
        )
    elif block.type == "mcp_tool_result":
        print(
            f"[tool_result] id={block.tool_use_id} is_error={getattr(block, 'is_error', False)}"
        )
        print(block.content)

The SDK sends the key as Authorization: Bearer <key> to TengineAI's MCP endpoint automatically.

Using an API Key with Direct REST Calls

For TengineAI management API calls (minting session tokens, registering assertion keys, etc.), pass the key using Authorization: Bearer:

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['TENGINEAI_API_KEY']}"}

# Example: list assertion keys for this project's integration
response = requests.get(
    "https://app.tengine.ai/api/v1/assertion-keys",
    headers=headers,
)
response.raise_for_status()
print(response.json())

Scope and Permissions

Each API key is tied to a specific integration within a project. It inherits the tool permissions and OAuth connections configured for that project.

• A key grants access to the tools enabled for its project
• A key cannot access other projects
• A key authenticates as the project, not as an individual user — all tool calls are unattributed

If you need per-user attribution, use User-Scoped Sessions instead.

Security Best Practices

Never commit API keys to source control. Always load them from environment variables or a secrets manager:

export TENGINEAI_API_KEY="tengine_..."

Rotate compromised keys immediately. See Rotating or Replacing a Key above.

Use separate keys per environment. Create one integration (and one API key) for development, another for staging, another for production. This limits blast radius if a key is exposed.

Next Steps

• User-Scoped Sessions – Per-user session tokens for multi-tenant apps
• Python Quick Start — API Key Mode – Full working example