Authentication

TinyFish uses different authentication methods depending on how you’re accessing the API:

Access Method	Auth Type	When to Use
REST API	API Key	Direct HTTP requests from your code
MCP Integration	OAuth 2.1	AI assistants (Claude, Cursor)

REST API Authentication

All REST API requests require an API key passed in the X-API-Key header.

Getting Your API Key

Go to the API Keys page

Visit agent.tinyfish.ai/api-keys

Create a new key

Click “Create API Key”

Copy and store your key

Copy and store your key securely

API keys are shown only once. Store them securely and never commit them to version control.

Using Your API Key

Pass your API key when making requests. The Python SDK reads TINYFISH_API_KEY from your environment automatically:

from tinyfish import TinyFish

client = TinyFish()  # Reads TINYFISH_API_KEY from environment

result = client.agent.run(
    url="https://example.com",
    goal="Extract the page title",
)

import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();  // Reads TINYFISH_API_KEY from environment

const response = await client.agent.run({
  url: "https://example.com",
  goal: "Extract the page title",
});

curl -X POST https://agent.tinyfish.ai/v1/automation/run \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "goal": "Extract the page title"}'

Environment Variables

Store your API key in an environment variable:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export TINYFISH_API_KEY="your_api_key_here"

For Node.js projects, use a .env file:

# .env
TINYFISH_API_KEY=your_api_key_here

Add .env to your .gitignore to prevent accidental commits.

MCP Authentication

The MCP endpoint uses OAuth 2.1 for secure authentication with AI assistants.

How It Works

Add the TinyFish MCP server

Add the TinyFish MCP server to your AI client configuration. See the MCP Integration guide for setup instructions.

Authenticate in browser

When you first use the tool, a browser window opens for authentication

Start using TinyFish Web Agent

Authorization is cached for future sessions

You need a TinyFish account. Search and Fetch are free; Agent and Browser draw from your wallet (plan credits on legacy accounts). Sign up here.

Error Responses

Authentication errors return standard HTTP status codes with a JSON error body. See Error Codes for the full reference.

401 Unauthorized — Missing API Key

The request is missing the X-API-Key header.

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "X-API-Key header is required"
  }
}

How to fix:

Add the X-API-Key header to your request
Check the header name is exactly X-API-Key (case-sensitive)

401 Unauthorized — Invalid API Key

The API key in the request is not valid.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

How to fix:

Verify your API key is correct
Ensure no extra whitespace around the key
Check if the key has been revoked or regenerated

# Debug: Check your key is set
echo $TINYFISH_API_KEY

# Debug: Test authentication
curl -I -X POST https://agent.tinyfish.ai/v1/automation/run \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "goal": "test"}'

403 Forbidden — Insufficient Credits (legacy accounts)

Authentication succeeded, but you lack credits or an active subscription. This applies to legacy credit/subscription accounts — wallet accounts get a 402 instead, see below.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient credits or no active subscription"
  }
}

How to fix:

Check your account at agent.tinyfish.ai/api-keys
Add credits to your account

402 Payment Required — Insufficient Credits (wallet accounts)

Your TinyFish wallet balance is too low to start this run. Non-retryable until money is added.

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Run not started: the user's TinyFish wallet balance is too low ($-2.50). This is not retryable and will keep failing until money is added. Tell the user to add money at https://agent.tinyfish.ai/wallet (minimum top-up $10), then try again.",
    "details": {
      "status": "failed",
      "error": "Run not started: the user's TinyFish wallet balance is too low ($-2.50). This is not retryable and will keep failing until money is added. Tell the user to add money at https://agent.tinyfish.ai/wallet (minimum top-up $10), then try again.",
      "reason": "wallet_out_of_funds",
      "non_retryable": true,
      "balance": "-2.50",
      "currency": "usd",
      "wallet_url": "https://agent.tinyfish.ai/wallet",
      "minimum_top_up": "10.00",
      "auto_reload_needs_payment_fix": false
    }
  }
}

How to fix:

Check your balance with GET /v1/wallet (or client.wallet.get(), tinyfish wallet status)
Add money at agent.tinyfish.ai/wallet — minimum top-up is $10
If auto_reload_needs_payment_fix is true, auto-reload is also paused on a declined payment method — update it on the same page

Not sure whether your account is on wallet or legacy billing? GET /v1/wallet returns 404 with error.code: "FEATURE_NOT_AVAILABLE" for legacy accounts — see Error Codes for the full discriminator.

Security Best Practices

Use Environment Variables

Never hardcode API keys in source code

Rotate Keys Regularly

Regenerate keys periodically and after team changes

Limit Exposure

Use separate keys for development and production

Monitor Usage

Review API usage in your dashboard for anomalies

Quick Start

Run your first automation

Error Codes

Full error code reference

Start Here

Agent API

Search API

Monitor (Beta)

Fetch API

Browser API

Research API (Beta)

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

REST API Authentication

Getting Your API Key

Using Your API Key

Environment Variables

MCP Authentication

How It Works

Error Responses

Security Best Practices

Use Environment Variables

Rotate Keys Regularly

Limit Exposure

Monitor Usage

Quick Start

Error Codes

​REST API Authentication

​Getting Your API Key

​Using Your API Key

​Environment Variables

​MCP Authentication

​How It Works

​Error Responses

​Security Best Practices

Use Environment Variables

Rotate Keys Regularly

Limit Exposure

Monitor Usage

​Related

Quick Start

Error Codes

REST API Authentication

Getting Your API Key

Using Your API Key

Environment Variables

MCP Authentication

How It Works

Error Responses

Security Best Practices

Related