Admin API Authentication
Admin API keys provide programmatic access to user resources. Admin keys are prefixed with admin_ and must be included in the Authorization header as a Bearer token.
Authorization: Bearer YOUR_ADMIN_KEY
Available Endpoints
Admin API keys can access the following endpoints:
API Key Management
GET /api/keys - List all API keysPOST /api/keys - Create a new API keyDELETE /api/keys/:key - Delete an API keyPOST /api/keys/rename - Rename an API key
Billing & Usage
GET /api/billing/usage - Get usage statisticsGET /api/billing/time-series - Get time series dataGET /api/billing/transactions - Get transaction history
API Key Management
List API Keys
Returns all regular (non-admin) API keys for the authenticated user.
Response
[
{
"key": "tk_...",
"name": "Production Key",
"clerk_user_id": "user_...",
"created_at": "2024-01-01T00:00:00Z",
"expires_at": "2024-12-31T23:59:59Z",
"max_tokens": 1000000,
"chat": false,
"is_admin": false,
"metadata": {
"environment": "production"
}
}
]
Create API Key
Creates a new regular API key for token-based API access.
Request Body
Name for the API key. Must contain only alphanumeric characters, hyphens, underscores, spaces, and periods.
ISO 8601 timestamp when the key should expire. If not provided, the key doesn’t expire.
Maximum number of tokens this key can use. If not provided, no limit is enforced.
Custom metadata to attach to the key. Maximum size: 5KB.
Example Request
curl -X POST https://api.tinfoil.sh/api/keys \
-H "Authorization: Bearer YOUR_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Production API Key",
"expires_at": "2024-12-31T23:59:59Z",
"max_tokens": 1000000,
"metadata": {
"environment": "production",
"team": "backend"
}
}'
Response
{
"key": "tk_newlyGeneratedKey123...",
"name": "Production API Key",
"clerk_user_id": "user_...",
"created_at": "2024-01-01T00:00:00Z",
"expires_at": "2024-12-31T23:59:59Z",
"max_tokens": 1000000,
"chat": false,
"is_admin": false,
"metadata": {
"environment": "production",
"team": "backend"
}
}
Delete API Key
Deletes a specific API key owned by the user.
Path Parameters
The API key to delete (e.g., tk_abc123...)
Example Request
curl -X DELETE https://api.tinfoil.sh/api/keys/tk_abc123 \
-H "Authorization: Bearer YOUR_ADMIN_KEY"
Response
{
"message": "API key deleted"
}
Rename API Key
Renames an existing API key.
Request Body
New name for the API key. Must contain only alphanumeric characters, hyphens, underscores, spaces, and periods.
Example Request
curl -X POST https://api.tinfoil.sh/api/keys/rename \
-H "Authorization: Bearer YOUR_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "tk_abc123...",
"name": "Staging API Key"
}'
Response
{
"message": "API key renamed"
}
Billing & Usage
Get Usage Statistics
Retrieves token usage statistics for the specified time period.
Query Parameters
Time period for usage statistics. Valid values:
5m - Last 5 minutes15m - Last 15 minutes30m - Last 30 minutes1h - Last hour24h - Last 24 hours7d - Last 7 days30d - Last 30 days60d - Last 60 days90d - Last 90 days
Example Request
curl "https://api.tinfoil.sh/api/billing/usage?time=7d" \
-H "Authorization: Bearer YOUR_ADMIN_KEY"
Response
{
"tokens": 1500000,
"requests": 3200,
"cost": 15.00,
"keys": {
"Production Key": {
"total_tokens": 1000000,
"total_requests": 2000,
"cost": 10.00,
"models": {
"deepseek-r1-0528": {
"tokens": 600000,
"requests": 1200,
"cost": 6.00
},
"gpt-oss-120b": {
"tokens": 400000,
"requests": 800,
"cost": 4.00
}
}
},
"Development Key": {
"total_tokens": 500000,
"total_requests": 1200,
"cost": 5.00,
"models": {
"qwen2-5-72b": {
"tokens": 500000,
"requests": 1200,
"cost": 5.00
}
}
}
}
}
Get Time Series Data
GET /api/billing/time-series
Retrieves time-series data for token usage over the specified period.
Query Parameters
Time period for the time series. Valid values:
5m - Last 5 minutes15m - Last 15 minutes30m - Last 30 minutes1h - Last hour24h - Last 24 hours7d - Last 7 days30d - Last 30 days60d - Last 60 days90d - Last 90 days
Example Request
curl "https://api.tinfoil.sh/api/billing/time-series?time=24h" \
-H "Authorization: Bearer YOUR_ADMIN_KEY"
Response
{
"data_points": [
{
"time": "2024-01-01T00:00:00Z",
"tokens": 50000,
"requests": 100,
"models": {
"mistral-small-3-1-24b": {
"tokens": 30000,
"requests": 60
},
"llama3-3-70b": {
"tokens": 20000,
"requests": 40
}
}
},
{
"time": "2024-01-01T02:24:00Z",
"tokens": 75000,
"requests": 150,
"models": {
"qwen3-coder-480b": {
"tokens": 75000,
"requests": 150
}
}
}
],
"interval": "2h24m0s"
}
Get Transaction History
GET /api/billing/transactions
Retrieves the transaction history including invoices and charges.
Example Request
curl "https://api.tinfoil.sh/api/billing/transactions" \
-H "Authorization: Bearer YOUR_ADMIN_KEY"
Response
[
{
"id": "in_1234567890",
"date": "2024-01-01T00:00:00Z",
"type": "Invoice",
"description": "Monthly subscription",
"amount": 99.00,
"status": "completed"
},
{
"id": "ch_0987654321",
"date": "2024-01-15T12:30:00Z",
"type": "Charge",
"description": "API Usage",
"amount": 25.50,
"status": "completed"
}
]
Error Responses
Example error response:
{
"status": "error",
"message": "Invalid admin API key"
}
