Admin API Documentation - Tinfoil Documentation

Introduction

The Admin API enables you to programmatically manage API keys, track usage, and monitor billing for your Tinfoil account. This is particularly powerful when combined with the encrypted request proxying architecture, where you want to track usage for each of your individual users while maintaining end-to-end encryption to the Tinfoil enclave.

Common Use Cases

Per-User Usage Tracking: The most common pattern is to create a separate Tinfoil API key for each of your users. When a user signs up for your service, use the Admin API to generate a dedicated API key for them and store it on your backend. Then, when proxying requests to Tinfoil, use that user’s specific API key. This allows you to query usage statistics per user using the Admin API’s ?key= parameter. Programmatic Key Management: Automate API key lifecycle management—create keys when users sign up, delete them when users leave, or set expiration dates and token limits based on your business logic. Custom Dashboards: Build internal dashboards that display usage metrics, cost breakdowns by user or by model, and historical trends using the time-series endpoints.

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

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 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.

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"
}

Per-User Usage Tracking

A common pattern for tracking usage on a per-user basis is to combine the Admin API with the encrypted request proxy architecture. Here’s how it works:

Workflow

User Signs Up: When a new user signs up for your service, use the Create API Key endpoint to generate a dedicated Tinfoil API key for them.
Store the Key: Save this API key on your backend, associated with the user’s account. You can use the metadata field to store your internal user ID for easy reference.
Proxy Requests: When your user makes inference requests, your proxy server uses that user’s specific Tinfoil API key in the Authorization header. The request body remains encrypted end-to-end from your user’s client to the Tinfoil enclave.
Track Usage: Query the Get Usage by Key endpoint with the user’s API key in the request body to retrieve usage and cost for that specific user.

Example: Creating a User-Specific Key

curl -X POST https://api.tinfoil.sh/api/keys \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User: [email protected]",
    "metadata": {
      "internal_user_id": "usr_12345",
      "email": "[email protected]"
    }
  }'

Example: Retrieving Usage for a Specific User

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

This returns simplified usage data for just that key:

{
  "prompt_tokens": 800000,
  "completion_tokens": 700000,
  "requests": 3200,
  "cost": 15.00
}

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:

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. This is the recommended approach for per-user usage tracking—create one API key per user and query their usage using this endpoint.

Query Parameters

time

string

Time period for usage statistics. If omitted, returns all-time usage. Valid values:

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": {
        "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"
}

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

​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

​Per-User Usage Tracking

​Workflow

​Example: Creating a User-Specific Key

​Example: Retrieving Usage for a Specific User

​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

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

Per-User Usage Tracking

Workflow

Example: Creating a User-Specific Key

Example: Retrieving Usage for a Specific User

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