Skip to content

API Keys

Jump to bottom
Niccanor Dhas edited this page Feb 22, 2026 · 1 revision

API Keys

API keys authenticate your application's SDK with the tmam server. Each key is scoped to a specific organization and project.

Key Format

tmam generates two values when you create an API key:

Key | Format | Purpose -- | -- | -- Public Key | pk-tmam-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | Identifies your key (safe to log) Secret Key | sk-tmam-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | Authenticates your requests (keep private)

⚠️ The secret key is shown only once at creation. Copy it immediately and store it securely. If lost, you must delete the key and create a new one. The server only stores a bcrypt hash of the secret — it cannot be recovered.

Creating an API Key

  1. Sign in to the dashboard
  2. Navigate to Settings → API Keys
  3. Select the Organization and Project the key should be scoped to
  4. Enter a descriptive name for the key (e.g. production-app, staging)
  5. Click Generate
  6. Copy both the public key and secret key — the secret is shown only once

Using API Keys in the SDK

Pass the keys to init():

from tmam import init

init(
url="http://localhost:5050/api/sdk",
public_key="pk-tmam-xxxxxxxx",
secrect_key="sk-tmam-xxxxxxxx",
application_name="my-app",
environment="production",
)

Or set them as environment variables:

export TMAM_URL="http://localhost:5050/api/sdk"
export TMAM_PUBLIC_KEY="pk-tmam-xxxxxxxx"
export TMAM_SECRET_KEY="sk-tmam-xxxxxxxx"

from tmam import init

init(application_name="my-app")  # reads keys from environment

How Authentication Works

The SDK sends the keys as HTTP headers on every request to /api/sdk:

X-Public-Key: pk-tmam-xxxxxxxx
X-Secret-Key: sk-tmam-xxxxxxxx

The server:

  1. Looks up the key record by public key
  2. Compares the incoming secret key against the stored bcrypt hash
  3. Grants access to the scoped organization and project if valid

The plaintext secret is never stored — only its hash. This means a leaked database does not expose valid SDK credentials.

Managing Keys

From Settings → API Keys you can:

  • View all keys — see key names, short previews, and when they were created
  • Copy public key — re-copy the public key at any time
  • Delete a key — immediately revokes all access for that key

Key Scoping

Each API key is bound to one organization and one project. All telemetry sent using a key is automatically attributed to that org/project combination in the dashboard.

To send data from multiple projects, create separate API keys for each.

Security Best Practices

  • Never commit keys to version control — use environment variables or a secrets manager
  • Use separate keys per environment (production, staging, dev) for clean data separation
  • Rotate keys regularly — delete the old key and create a new one
  • Use descriptive names so you can identify which key belongs to which service
  • Restrict access — only admins can create and delete keys within an organization

Clone this wiki locally