Admin API Documentation - Tinfoil Documentation

Introduction

The Admin API allows you to programmatically manage your account’s resources, including API keys, usage metrics, and billing. This provides programmatic control over administrative tasks that would otherwise require manual configuration in the Tinfoil Dashboard.

Common Use Cases

Automating key management: Create, rotate, or delete API keys programmatically, and set expiration dates or token limits based on your business logic.
Building custom dashboards: Display usage metrics, cost breakdowns by model, and historical trends using the billing and time-series endpoints.
Monitoring usage: Query aggregated or per-key usage statistics to track costs and token consumption.

If you need per-user usage metrics for billing, the recommended approach is to run a proxy server that tracks token counts via response headers — rather than creating a separate API key per user in your system.

Authentication

Admin API keys provide programmatic access to your account 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

Admin keys provide programmatic access to organization settings, including managing API keys, setting rate limits, and modifying billing configuration. Do not share admin keys or expose them in browsers, client-side code, or public repositories. Organization-scoped admin keys may remain active even after the creator is removed from the organization.

Authorization: Bearer YOUR_ADMIN_KEY

Available Endpoints

Admin API keys can access the following endpoints:

API Key Management

GET /api/keys - List 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 aggregated usage statistics for all keys
POST /api/billing/usage/key - Get usage statistics for a specific key
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.

Example Request

curl "https://api.tinfoil.sh/api/keys" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

Response

[
  {
    "key": "tk_...",
    "clerk_user_id": "user_...",
    "chat": false,
    "name": "Production Key",
    "disabled": false,
    "expires_at": "2024-12-31T23:59:59Z",
    "max_tokens": 1000000,
    "is_admin": false,
    "metadata": {
      "environment": "production"
    },
    "clerk_org_id": null,
    "created_at": "2024-01-01T00:00:00"
  }
]

Create API Key

POST /api/keys

endpoint

Creates a new regular API key for token-based API access. Requires an active API billing subscription.

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...",
  "clerk_user_id": "user_...",
  "chat": false,
  "name": "Production API Key",
  "disabled": false,
  "expires_at": "2024-12-31T23:59:59Z",
  "max_tokens": 1000000,
  "is_admin": false,
  "metadata": {
    "environment": "production",
    "team": "backend"
  },
  "clerk_org_id": null,
  "created_at": "2024-01-01T00:00:00"
}

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 aggregated token usage statistics for all keys for the specified time period.

Query Parameters

time

string

Time period for usage statistics. If omitted, returns all-time usage. 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": {
        "llama3-3-70b": {
          "tokens": 500000,
          "requests": 1200,
          "cost": 5.00
        }
      }
    }
  }
}

Get Usage by Key

POST /api/billing/usage/key

endpoint

Retrieves token usage statistics for a specific API key owned by the authenticated user.

Query Parameters

time

string

Time period for usage statistics. If omitted, returns all-time usage. 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

Request Body

key

string

required

The API key to query usage for (e.g., tk_abc123...).

Example Request

curl -X POST "https://api.tinfoil.sh/api/billing/usage/key?time=7d" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "tk_abc123..."}'

Response

{
  "prompt_tokens": 800000,
  "completion_tokens": 700000,
  "requests": 3200,
  "cost": 15.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": {
        "deepseek-r1-0528": {
          "tokens": 30000,
          "requests": 60
        },
        "llama3-3-70b": {
          "tokens": 20000,
          "requests": 40
        }
      }
    },
    {
      "time": "2024-01-01T02:24:00Z",
      "tokens": 75000,
      "requests": 150,
      "models": {
        "kimi-k2-5": {
          "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

{
  "transactions": [
    {
      "id": "in_1234567890",
      "date": "2024-01-01T00:00:00Z",
      "type": "Invoice",
      "description": "Monthly subscription",
      "amount": 99.00,
      "status": "completed",
      "invoice_url": "https://invoice.stripe.com/i/..."
    },
    {
      "id": "ch_0987654321",
      "date": "2024-01-15T12:30:00Z",
      "type": "Charge",
      "description": "API Usage",
      "amount": 25.50,
      "status": "completed"
    }
  ]
}

Error Responses

Example error response:

{
  "error": "invalid admin API key",
  "code": "UNAUTHORIZED"
}

Common error codes:

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or expired admin API key
`BAD_REQUEST`	400	Invalid request parameters
`NOT_FOUND`	404	Resource not found
`PAYMENT_REQUIRED`	402	Active subscription required
`INTERNAL_ERROR`	500	Server error

Getting Started

Models

SDKs

Guides

Privacy Verification

Tutorials

Admin API

Confidential Computing

Resources

​Introduction

​Common Use Cases

​Authentication

​Available Endpoints

​API Key Management

​Billing & Usage

​API Key Management

​List API Keys

​Example Request

​Response

​Create API Key

​Request Body

​Example Request

​Response

​Delete API Key

​Path Parameters

​Example Request

​Response

​Rename API Key

​Request Body

​Example Request

​Response

​Billing & Usage

​Get Usage Statistics

​Query Parameters

​Example Request

​Response

​Get Usage by Key

​Query Parameters

​Request Body

​Example Request

​Response

​Get Time Series Data

​Query Parameters

​Example Request

​Response

​Get Transaction History

​Example Request

​Response

​Error Responses

Introduction

Common Use Cases

Authentication

Available Endpoints

API Key Management

Billing & Usage

API Key Management

List API Keys

Example Request

Response

Create API Key

Request Body

Example Request

Response

Delete API Key

Path Parameters

Example Request

Response

Rename API Key

Request Body

Example Request

Response

Billing & Usage

Get Usage Statistics

Query Parameters

Example Request

Response

Get Usage by Key

Query Parameters

Request Body

Example Request

Response

Get Time Series Data

Query Parameters

Example Request

Response

Get Transaction History

Example Request

Response

Error Responses