Authentication

Y2 authenticates most API requests with a workspace-bound bearer key. Endpoints that explicitly support x402 also offer a separate paid request path when no bearer key is sent.

Authentication flow

Plan requirements

Existing keys that were already eligible under the Lite grace policy remain visible, usable, rotatable, and revocable. A later downgrade from Pro or Elite marks keys plan-ineligible; it does not create new Lite grace access.

Rate limits apply per key and again to the account aggregate: the workspace for workspace-bound keys, or the user for a legacy unscoped key. Creating more keys does not multiply the tenant quota.

Create a key

Key format and storage

Y2 generates 32 random bytes and encodes them as 64 hexadecimal characters after the y2_ prefix:

y2_{64 lowercase hexadecimal characters}

Only the SHA-256 hash and a short display prefix are stored. The dashboard cannot retrieve the plaintext later. Regeneration creates new secret material and immediately invalidates the prior value.

Send the key

curl -sS -D - "https://api.y2.dev/api/v1/reports?limit=1" \
  -H "Authorization: Bearer $Y2_API_KEY"

The authentication scheme is the case-sensitive Bearer prefix followed by the key. Keep the credential server-side; never place it in a browser bundle, query string, prompt, tool argument, or log message.

Workspace scope

Do not accept a user-provided workspaceId as authorization. If an operation accepts a resource ID, the backend still verifies that the resource belongs to the tenant resolved from the key.

Scopes

An array of required Intel scopes in the generated reference means any one of the listed scopes can authorize that shared endpoint. Always check the exact operation's x-required-scopes value.

Plan entitlements are enforced again during key validation. Storing a scope on a key does not keep that capability active after the workspace loses the required plan feature.

intel:knowledge and agent:y2 are intentionally separate. Direct POST /api/v2/intel/knowledge/retrieve calls require intel:knowledge. Agent Y2 routes continue to require only agent:y2; an entitled agent can invoke Global Knowledge through the shared internal tool. Existing keys are never expanded automatically—edit or rotate a key deliberately when an integration needs intel:knowledge, projects:*, automations:*, or ledger:*.

Workspace research endpoints require a workspace-bound key: company financial history (intel:finint), cyber-market fusion (intel:explorer), and the ontology ledger (ledger:*). A personal key receives 403, and x402 payment is not accepted for them.

IP allowlisting

The dashboard's IP restriction currently performs an exact string comparison against the client IP resolved from CF-Connecting-IP, the first X-Forwarded-For value, or X-Real-IP.

• Enter individual IPv4 or IPv6 addresses only.
• CIDR ranges are not parsed by the current middleware.
• For hosted jobs, allow the service's public egress IP, not a private container address.
• Removing every entry disables the key-specific IP restriction.
• A resolved address not present in the list returns 403 with IP_NOT_ALLOWED.

x402 selection

On an x402-enabled operation, the request path is selected by the header prefix:

Do not send a placeholder bearer header when you intend to use x402. See the x402 guide and the operation's generated reference for price, network, and payment headers.

Rate-limit headers

Y2 uses fixed UTC minute and day windows. Authenticated responses expose both pools:

Agent Y2 adds a third, endpoint-specific header family. See Agent Y2 rate limits.

Rotate, revoke, or delete

For routine rotation, deploy support for the replacement secret before invalidating the old key if your architecture allows parallel credentials. The dashboard's Regenerate action does not provide an overlap window for the same key record.

Errors and lockout

Y2 API errors use RFC 9457-style problem details with an actionable resolution hint:

{
  "type": "https://api.y2.dev/problems/insufficient-scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions. Requires reports:read scope",
  "instance": "urn:y2:request:req_...",
  "code": "INSUFFICIENT_SCOPE",
  "requestId": "req_...",
  "resolution": "Verify that the API key belongs to the intended workspace and grants the required scope."
}

Five invalid or unknown key attempts from one resolved IP within 15 minutes trigger an authentication lockout for that rolling window. Revoked, expired, and plan-ineligible known keys do not count as brute-force failures. If a valid key suddenly receives a pre-validation 429, stop retrying and wait for the lockout window to clear.

Related reference