Authentication

How to authenticate with the TinyFish API

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

1. Go to the API Keys page

   Visit agent.tinyfish.ai/api-keys

2. Create a new key

   Click “Create API Key”

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

Python

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",
)

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

1. Add the TinyFish MCP server

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

2. Authenticate in browser

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

3. Log in

   Log in with your TinyFish account

4. Start using TinyFish Web Agent

   Authorization is cached for future sessions

You need a TinyFish account with an active subscription or credits. 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

Authentication succeeded, but you lack credits or an active subscription.

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

How to fix:

• Check your account at agent.tinyfish.ai/api-keys
• Add credits or upgrade your plan

---

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

---

Related

Quick Start

Run your first automation

Error Codes

Full error code reference