Documentation

Till lets you create scoped API keys for AI agents with activation, token, and dollar limits. Give agents disposable keys instead of your real ones. Whichever limit hits first kills the key.

New to Till? Follow the Quick Start to create your first scoped key in under a minute. No credit card needed.

Quick Start

Create an account Sign up at till.ac. You'll get an admin key instantly. Save it - it's only shown once.
Install the Python SDK pip install till-ac - or use the REST API directly.
Create a scoped key Set limits and get a disposable key your agent can use as a drop-in replacement.

from till import TillClient

client = TillClient(admin_key="till_admin_...")

# Create a scoped key: 50 activations, 100K tokens, $5 budget
key = client.create_key(
    provider="openai",
    upstream_key="sk-proj-...",
    max_activations=50,
    max_tokens=100_000,
    max_spend_cents=500,
)

# Give to agent - drop-in OpenAI compatible
from till.openai_compat import patched_openai
ai = patched_openai(key.scoped_key)
response = ai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

Python SDK

The official Python SDK is the fastest way to work with Till.

pip install till-ac

The SDK provides:

TillClient - create, list, check, and revoke scoped keys
patched_openai() - drop-in wrapper that routes OpenAI-compatible requests through Till's proxy
Key status checking - inspect remaining activations, tokens, and spend before using a key

Full SDK docs and source: pypi.org/project/till-ac

Scoped Keys

A scoped key is a disposable proxy key that wraps your real upstream API key with enforced limits. The format:

till_sk_<lookupKey>.<encryptedUpstreamKey>

# Example (truncated):
till_sk_mz90mM7bQ...VtkE.aGVsbG8gd29ybGQ...

When an agent makes a request with a scoped key, Till:

Extracts the lookup key and finds the key record in the database
Checks all three limits (activations, tokens, dollars)
Decrypts the upstream key from the token (AES-256-GCM)
Forwards the request to the upstream provider
Tracks usage from the response and increments counters

Three Limits

Every scoped key can have up to three independent limits. Whichever hits first kills the key.

Activation limit - each proxied HTTP request counts as one activation. 50 activations means 50 API calls, regardless of how many tokens each uses.
Token limit - caps total input + output tokens. Tracked automatically from upstream response headers. Ideal for controlling context window costs.
Dollar limit - sets a dollar budget. Till has built-in pricing for 80+ models across all 11 providers. $5 means $5, not $500.

You can set any combination. A key with only an activation limit and no token/dollar limit works fine. So does a key with only a dollar limit.

Providers

Till supports 11 AI providers. All OpenAI-compatible providers use the same proxy path format:

OpenAI - GPT-4o, o1, o3, GPT-4 Turbo, etc.
Anthropic - Claude 4, Opus, Sonnet, Haiku
Google - Gemini 2.5 Pro, Flash, etc.
OpenRouter - access hundreds of models through one integration
Mistral - Mistral Large, Medium, Small
Groq - ultra-fast inference (Llama, Mixtral)
Together AI - open-source model hosting
Fireworks AI - fast inference at scale
Perplexity - search-augmented models
DeepSeek - DeepSeek-V3, Coder, Reasoner
xAI - Grok models
Cohere - Command R, Embed, Rerank

Zero-Knowledge Architecture

Till's database stores zero upstream API keys. Here's how:

When you create a scoped key, your upstream API key is AES-256-GCM encrypted and embedded directly into the scoped token string. The database stores only:

A hash of the lookup portion (for finding the key record)
Activation counter and limit
Token and dollar usage counters
Key metadata (provider, status, created timestamp)

If the Till database were breached, the attacker would find zero upstream keys. They're not there. The encrypted key material lives only in the scoped token you hold.

Authentication

All admin API requests require your admin key in the Authorization header:

# Admin operations (create keys, check status, etc.)
Authorization: Bearer till_admin_your_key_here

The proxy endpoint uses the scoped key itself as authorization - your agent just uses it like a normal API key.

API Endpoints

Base URL: https://api.till.ac

Create a scoped key

POST /admin/keys

{
  "provider": "openai",
  "upstream_key": "sk-proj-...",
  "max_activations": 50,
  "max_tokens": 100000,
  "max_spend_cents": 500,
  "metadata": {"name": "agent-task-42"}
}

List keys

GET /admin/keys

Check key status

GET /admin/keys/:id

Revoke a key

DELETE /admin/keys/:id

Proxy Usage

To use a scoped key, keep the same request paths your SDK already uses and point the base URL to Till:

# Instead of:
base_url = "https://api.openai.com/v1"
api_key  = "sk-proj-your-real-key"

# Use:
base_url = "https://api.till.ac/v1"
api_key  = "till_sk_your-scoped-key"

Common passthrough paths:

POST /v1/chat/completions (OpenAI-compatible)
POST /v1/messages (Anthropic)
POST /v1beta/models/{model}:generateContent (Google)

The proxy transparently forwards requests, tracks usage, and enforces limits. From the agent's perspective, only the base URL and API key change.

Plans

Free - 3 scoped keys, 1,000 activations/month
Pro ($29/mo) - 25 keys, 25,000 activations/month, IP allowlisting
Scale ($99/mo) - 100 keys, 250,000 activations/month, dedicated support

All plans include all 11 providers, all three limit types, the dashboard, and the Python SDK.

FAQ

What counts as one activation?

One proxied HTTP request equals one activation. A 20-message conversation equals 20 activations (one per API call). A streaming response is still one activation.

Can I set only one type of limit?

Yes. Any combination works. Activation-only, dollar-only, all three, or any pair. Whichever limit you set is enforced. Unset limits are unlimited (within your plan's monthly cap).

How accurate is dollar tracking?

Till uses built-in pricing data for 80+ models. It reads token counts from upstream response headers and calculates cost immediately. Accuracy is within pennies of the actual provider bill.

What happens when a key expires?

Any request using an exhausted key gets a clear error response with the reason (activation limit, token limit, or dollar limit reached). The agent can handle this gracefully.

Can I use Till with frameworks like LangChain or LlamaIndex?

Yes. Any framework that lets you set a custom base_url and API key works with Till. The proxy is fully API-compatible with each upstream provider.