Skip to main content
TinyFish uses different authentication methods depending on how you’re accessing the API:
Access MethodAuth TypeWhen to Use
REST APIAPI KeyDirect HTTP requests from your code
MCP IntegrationOAuth 2.1AI 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

Include the X-API-Key header in every request: 
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

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.
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)
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"}'
Authentication succeeded, but you lack credits or an active subscription.
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient credits or no active subscription"
  }
}
How to fix:

​
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