Get Started
Create a Site
Create a site, upload images, and configure puzzles to get your API keys.
Before embedding the widget, you need to create a site in the yCAPTCHA dashboard to get your Site Key and Secret Key.
1. Create a site
- Log into the yCAPTCHA dashboard.
- Navigate to Sites and click Create Site.
- Give your site a name (e.g., "My Blog", "Login Page").
- Your site will be issued two keys:
| Key | Format | Purpose |
|---|---|---|
| Site Key | pk_... | Public. Used in the widget iframe URL. |
| Secret Key | sk_... | Private. Used only on your server for verification. |
Never expose your Secret Key in client-side code. It should only be used in server-to-server API calls.
2. Upload images
- Navigate to Image Sets in the dashboard.
- Create a new image set (e.g., "NYC Parks", "Fire Hydrants").
- Upload the images you want to use in your challenges.
Image sets are owned by your account, not a specific site. You can reuse the same image set across multiple sites.
3. Create a puzzle
- Navigate to your site's Puzzles section.
- Click Create Puzzle and configure:
| Setting | Description |
|---|---|
| Image Set | Select which image pool to use for this puzzle. |
| Prompt | The keyword shown to users (e.g., parks). The widget adds a fixed instruction prefix. |
| Correct Images | Mark which images in the set are the right answers. |
| Incorrect Images | Optionally hand-pick distractors. If left empty, they are drawn randomly from the pool. |
| Difficulty | Float from 0 to 1 (default 0.5). Controls how many correct selections are required to pass. |
Prompt
Enter just the keyword (e.g., parks, fire hydrants). The widget always displays "Select all images with" as the instruction prefix.
Difficulty
The pass threshold is calculated as:
requiredCorrect = Math.ceil(correctImageCount * difficulty)For example, with 3 correct images and difficulty 0.5, the user needs to select at least 2 correct images.
Next steps
Once you have a site with at least one puzzle configured:
- Embed the Widget on your webpage
- Validate tokens on your server