Authentication

How Authentication Works

Every You.com API request requires an API key, passed in the X-API-Key header. Get a key from the Platform API Keys page — new accounts start with $100 in complimentary credits.

$
curl -G https://api.you.com/v1/search \
>
  -H "X-API-Key: $YDC_API_KEY" \
>
  --data-urlencode "query=global birth rate trends"

For key creation, rotation, and revocation, see API Key Management. This page covers how a request is authenticated, not how the key itself is managed.

The YDC_API_KEY Convention

All code samples in these docs read the key from an environment variable named YDC_API_KEY. It is the canonical variable name across the docs, the SDKs, and every integration example. Set it once and the samples pick it up.

$
export YDC_API_KEY="<YDC_API_KEY>"

1
import os
2
from youdotcom import You
3
4
with You(api_key_auth=os.environ["YDC_API_KEY"]) as you:
5
    results = you.search.unified(query="global birth rate trends")

1
import { You } from "@youdotcom-oss/sdk";
2
3
const you = new You({ apiKeyAuth: process.env.YDC_API_KEY });

Never hardcode the key in source. Keep it in an environment variable or a secrets manager, and add .env files to .gitignore.

Scopes and 403 Responses

API keys are scoped per product. A key without access to a given path returns 403 Forbidden with {"detail": "Missing required scopes"} — for example, calling /v1/contents with a key that only has Web Search API access.

If you need access to an API your current key does not cover, create a new key with the right scope from the Platform.

Keyless Access via the Free MCP Profile

You can try the Web Search API without an API key by connecting any MCP-enabled client to api.you.com/mcp?profile=free and using the you-search tool. The free profile is limited to 100 queries per day and does not include you-contents, you-research, or you-finance. For setup, see the MCP Server guide.

Alternatively, you can hit the free search endpoint directly: api.you.com/v1/agents/search. For example, run this in your terminal:

$
curl -G https://api.you.com/v1/agents/search?query=global+birth+rate+trends

For everything beyond evaluation, use an API key.