Authentication

API Keys

The TheTerms API uses API keys for authentication. Each key is tied to a single organisation and grants access to all resources within that organisation.

Creating an API Key

1. Log in to your TheTerms dashboard
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Give it a descriptive name (e.g., “CI/CD Pipeline”, “CRM Integration”)
5. Copy the key immediately — it is shown only once

Caution

API keys are displayed only once at creation time. Store them securely. If you lose a key, revoke it and create a new one.

Using Your API Key

Include the key in the X-Api-Key header on every request:

curl

curl https://app.theterms.app/api/v1/containers \
  -H "X-Api-Key: tt_your_api_key_here"

JavaScript

const response = await fetch("https://app.theterms.app/api/v1/containers", {
  headers: {
    "X-Api-Key": "tt_your_api_key_here",
  },
});
const data = await response.json();

Python

import requests

response = requests.get(
    "https://app.theterms.app/api/v1/containers",
    headers={"X-Api-Key": "tt_your_api_key_here"},
)
data = response.json()

Key Format

API keys follow this format:

tt_<64 hex characters>

The tt_ prefix identifies it as a TheTerms API key. The server stores only a SHA-256 hash of the key — the raw key is never stored.

Key Limits

• Maximum 5 active API keys per organisation
• Keys can be revoked at any time from the dashboard
• Revoked keys are rejected immediately

Permissions

API keys currently operate with Admin permissions within the organisation. This means the key can:

• Read all resources (containers, documents, signing requests, webhooks)
• Create and modify documents and signing requests
• Manage containers and webhooks

Note

Per-key permission scoping (e.g., read-only keys) is planned for a future release.

Error Responses

Status	Meaning
401 Unauthorized	Missing X-Api-Key header, invalid key, or revoked key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Security Best Practices

• Never commit API keys to version control. Use environment variables.
• Rotate keys regularly. Revoke old keys and create new ones periodically.
• Use one key per integration. This makes it easy to revoke access for a specific system without disrupting others.
• Monitor usage. Check the last_used_at timestamp on the dashboard to detect stale keys.