​
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.
Need to create an admin API key? Follow our step-by-step guide: Getting a Tinfoil Admin Key
Authorization: Bearer YOUR_ADMIN_KEY

​
Available Endpoints

Admin API keys can access the following endpoints:

​
API Key Management

  • GET /api/keys - List all API keys
  • POST /api/keys - Create a new API key
  • DELETE /api/keys/:key - Delete an API key
  • POST /api/keys/rename - Rename an API key

​
Billing & Usage

  • GET /api/billing/usage - Get usage statistics
  • GET /api/billing/time-series - Get time series data
  • GET /api/billing/transactions - Get transaction history

​
API Key Management

​
List API Keys

​
GET /api/keys
endpoint
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

​
POST /api/keys
endpoint
Creates a new regular API key for token-based API access.

​
Request Body

​
name
string
required
Name for the API key. Must contain only alphanumeric characters, hyphens, underscores, spaces, and periods.
​
expires_at
datetime
ISO 8601 timestamp when the key should expire. If not provided, the key doesn’t expire.
​
max_tokens
integer
Maximum number of tokens this key can use. If not provided, no limit is enforced.
​
metadata
object
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

​
DELETE /api/keys/:key
endpoint
Deletes a specific API key owned by the user.

​
Path Parameters

​
key
string
required
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

​
POST /api/keys/rename
endpoint
Renames an existing API key.

​
Request Body

​
key
string
required
The API key to rename.
​
name
string
required
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

​
GET /api/billing/usage
endpoint
Retrieves token usage statistics for the specified time period.

​
Query Parameters

​
time
string
default:"24h"
Time period for usage statistics. Valid values:
  • 5m - Last 5 minutes
  • 15m - Last 15 minutes
  • 30m - Last 30 minutes
  • 1h - Last hour
  • 24h - Last 24 hours
  • 7d - Last 7 days
  • 30d - Last 30 days
  • 60d - Last 60 days
  • 90d - 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
endpoint
Retrieves time-series data for token usage over the specified period.

​
Query Parameters

​
time
string
default:"24h"
Time period for the time series. Valid values:
  • 5m - Last 5 minutes
  • 15m - Last 15 minutes
  • 30m - Last 30 minutes
  • 1h - Last hour
  • 24h - Last 24 hours
  • 7d - Last 7 days
  • 30d - Last 30 days
  • 60d - Last 60 days
  • 90d - 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
endpoint
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"
}