Authentication

All API requests require a valid API key. This page covers how keys work, how to manage them, and best practices for keeping them secure.

API Key Format

uCaptcha API keys use the ucap_ prefix followed by a random alphanumeric string:

ucap_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The prefix makes it easy to identify uCaptcha keys in your configuration and to set up secret scanning rules in your repositories.

Getting Your API Key

Open @uCaptcha_bot on Telegram.
Your account is created automatically on first interaction.
An API key is generated for you immediately.

No email, no signup form, no verification. You can start making API calls right away.

Managing Keys

Open the uCaptcha Telegram Mini App (via the bot menu) and navigate to the API tab. From there you can:

View all your API keys
Create additional keys
Rename keys for easy identification
Configure routing settings per key
Set IP whitelists per key
Revoke keys

Modern API Authentication

For the JSON API endpoints (/createTask, /getTaskResult, /getBalance), pass your key as the clientKey field in the request body:

{
  "clientKey": "ucap_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "task": {
    "type": "ReCaptchaV2TokenProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "SITE_KEY"
  }
}

Legacy API Authentication

For 2captcha-compatible endpoints (/in.php, /res.php), pass your key as the key query parameter:

https://api.ucaptcha.net/in.php?key=ucap_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6&method=userrecaptcha&googlekey=SITE_KEY&pageurl=https://example.com

Multiple API Keys

You can create multiple API keys, each with independent configuration:

Routing mode — NORMAL (provider auto-selection) or LIGHTNING (pre-solved token pool)
Speed/Cost slider — A 0-100 slider that controls the tradeoff. 0 = cheapest provider, 100 = fastest provider. Values in between use the Pareto frontier to find the optimal balance.
Routing preset — Cheapest, Fastest, Reliable, or Custom. Presets configure the sliders for you, or switch to Custom to fine-tune.

This lets you use different routing strategies for different parts of your application. For example:

A key for background scraping configured for cheapest routing
A key for user-facing flows configured for fastest routing
A key with Lightning mode for high-throughput pipelines

IP Whitelisting

Each API key supports an optional IP whitelist for added security:

Up to 10 IP addresses per key
When at least one IP is configured, requests from non-whitelisted IPs are rejected with an ERROR_IP_NOT_ALLOWED error
Leave the whitelist empty to allow all IPs (default)
Manage whitelists in the Telegram Mini App under each key’s settings

Per-Key Routing Modes

Each API key operates in one of two routing modes:

NORMAL mode (default):

Tasks are routed to providers in real time based on your speed/cost slider position
The routing engine evaluates provider availability, pricing, and historical performance
Best for most use cases

LIGHTNING mode:

uCaptcha maintains a pool of pre-solved tokens for popular CAPTCHA types
When you create a task, a ready token is returned immediately if one is available in the pool
Falls back to NORMAL mode if no pre-solved token is available
Best for latency-sensitive, high-throughput applications
Enable per key in the Mini App

Security Best Practices

Use IP whitelisting in production environments to restrict key usage to your server IPs.
Use separate keys for separate applications or environments (development, staging, production).
Rotate keys periodically. Create a new key, update your application, then revoke the old key.
Monitor usage in the Telegram Mini App to detect unexpected activity.
Add your repository to a secret scanning service to catch accidental key commits. The ucap_ prefix makes this straightforward.